--- updatedAt: 2026-06-04T19:57:42.000Z agentTools: projectIndex: https://docs.wristband.dev/llms.txt --- # Introspect New User Invitation External IdP Auth Code Introspects an external IdP auth code associated with a new user invitation request. Introspection performs the following operations: * Verifies that the external IdP auth code is still valid. * Returns information related to the new user invitation request associated with the external IdP auth code. ### Required Permissions Below is the list of required permissions needed to interact with this API. For each permission, the allowed permission boundaries are also specified. | Permission | Boundary | Description | | ---------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | **new-user-invitation-workflow:execute** | Application | The subject can perform this operation for requests associated with the application to which the subject belongs. | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Workflow APIs", "version": "1.0.0", "description": "Workflow APIs", "license": { "name": "Private", "url": "https://wristband.dev/terms/" }, "termsOfService": "https://wristband.dev/terms/", "contact": { "name": "Wristband Support", "email": "support@wristband.dev", "url": "https://wristband.dev/contact/" } }, "servers": [ { "url": "https://{application_vanity_domain}", "description": "Wristband application scoped URL.", "variables": { "application_vanity_domain": { "default": "yourapp-yourorg.us.wristband.dev", "description": "Wristband vanity domain scoped to a specific application." } } } ], "tags": [ { "name": "New User Invitation", "description": "New User Invitation", "x-displayName": "New User Invitation" } ], "paths": { "/api/v1/new-user-invitation/external-idp/introspect": { "post": { "summary": "Introspect New User Invitation External IdP Auth Code", "operationId": "introspectNewUserInvitationExternalIdpAuthCodeV1", "tags": [ "New User Invitation" ], "security": [ { "Workflow_APIs_BearerAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Workflow_APIs_TokenIntrospectionRequestRequestBody" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_NewUserInvitationIntrospectionResponse" }, "examples": { "Example 1": { "$ref": "#/components/examples/Workflow_APIs_NewUserInvitationIntrospectionResponse" } } } } }, "400": { "$ref": "#/components/responses/Workflow_APIs_400-with-message-body" }, "401": { "$ref": "#/components/responses/Workflow_APIs_401" }, "405": { "$ref": "#/components/responses/Workflow_APIs_405" }, "406": { "$ref": "#/components/responses/Workflow_APIs_406" }, "415": { "$ref": "#/components/responses/Workflow_APIs_415" }, "500": { "$ref": "#/components/responses/Workflow_APIs_500" }, "503": { "$ref": "#/components/responses/Workflow_APIs_503" } } } } }, "components": { "securitySchemes": { "Workflow_APIs_BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "Workflow_APIs_401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "description": "Includes details on the failed authentication condition. This header is set in accordance with the [OAuth2 specification](https://datatracker.ietf.org/doc/html/rfc6750#section-3).", "schema": { "type": "string", "example": "Bearer error=\"invalid_token\", error_description=\"The provided access token was invalid\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, "examples": { "code - unauthenticated": { "value": { "type": "base_error", "code": "invalid_access_token", "message": "The provided access token was invalid", "ticket": "1u0d0edhwbjsd" } } } } } }, "Workflow_APIs_405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, "examples": { "code - method_not_supported": { "value": { "type": "base_error", "code": "method_not_supported", "message": "The specified HTTP method is not supported", "ticket": "11t7n71hi5e6t" } } } } } }, "Workflow_APIs_406": { "description": "Not Acceptable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, "examples": { "code - not_acceptable": { "value": { "type": "base_error", "code": "not_acceptable", "message": "The Accept header was invalid", "ticket": "11t7n71hi5e6t" } } } } } }, "Workflow_APIs_415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, "examples": { "code - unsupported_media_type": { "value": { "type": "base_error", "code": "unsupported_media_type", "message": "The Content-Type header was invalid", "ticket": "11t7n71hi5e6t" } } } } } }, "Workflow_APIs_500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, "examples": { "code - internal_server_failure ": { "value": { "type": "base_error", "code": "internal_server_failure", "message": "An unexpected error occurred while processing the request", "ticket": "11t7n71hi5e6t" } } } } } }, "Workflow_APIs_503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, "examples": { "code - service_unavailable": { "value": { "type": "base_error", "code": "service_unavailable", "message": "The service is currently unavailable", "ticket": "11t7n71hi5e6t" } } } } } }, "Workflow_APIs_400-with-message-body": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, { "$ref": "#/components/schemas/Workflow_APIs_constraint-violations-api-error" } ] }, "examples": { "code - invalid_request": { "value": { "type": "base_error", "code": "invalid_request", "message": "The request was invalid", "ticket": "11t7n71hi5e6t" } }, "code - request_constraint_violations": { "value": { "type": "constraint_violations_error", "code": "message_body_constraint_violations", "message": "The message body contained invalid fields", "ticket": "11t7n71hi5e6t", "violations": { "field1": { "code": "too_long", "constraintAttributes": { "maxLength": 10 } }, "field2": { "code": "not_null" } } } }, "code - message_body_constraint_violations": { "value": { "type": "constraint_violations_error", "code": "message_body_constraint_violations", "message": "The message body contained invalid fields", "ticket": "11t7n71hi5e6t", "violations": { "field1": { "code": "too_long", "constraintAttributes": { "maxLength": 10 } }, "field2": { "code": "not_null" } } } } } } } } }, "schemas": { "Workflow_APIs_api-error": { "title": "ApiError", "type": "object", "description": "API error object", "x-examples": { "Example 1": { "code": "invalid_request", "message": "The request was invalid", "ticket": "11t7n71hi5e6t" } }, "properties": { "type": { "type": "string", "example": "base_error", "minLength": 1, "description": "The type of the API error.", "readOnly": true }, "code": { "type": "string", "example": "invalid_request", "minLength": 1, "description": "A code identifying the error that occurred.", "readOnly": true }, "message": { "type": "string", "example": "The request was invalid", "description": "A free text message describing the error. This error message is only meant to help developers understand the cause of the error. It should not be used for programmatic purposes.", "readOnly": true }, "ticket": { "type": "string", "example": "11t7n71hi5e6t", "description": "Ticket that can help correlate the error to the backend", "readOnly": true }, "details": { "type": "object", "description": "A map of details about the error. The keys are defined by the API.", "additionalProperties": {}, "example": { "attemptsRemaining": 4 } } }, "required": [ "type", "code" ] }, "Workflow_APIs_constraint-violations-api-error": { "title": "ConstraintViolationsApiError", "description": "An API error that occurred due to a constraint violation", "allOf": [ { "$ref": "#/components/schemas/Workflow_APIs_api-error" }, { "type": "object", "readOnly": true, "required": [ "violations" ], "properties": { "violations": { "type": "object", "readOnly": true, "required": [ "code" ], "properties": { "code": { "type": "string", "description": "A code identifying the constraint violation.", "minLength": 1, "example": "too_long" }, "constraintAttributes": { "type": "object", "description": "A map of constraint attribute values.", "additionalProperties": { "type": "string" }, "example": { "maxLength": "10" } } } } } } ], "x-examples": { "Example 1": { "type": "constraint_violations_error", "code": "message_body_constraint_violations", "message": "The request contained invalid fields", "ticket": "11t7n71hi5e6t", "violations": { "field1": { "code": "too_long", "constraintAttributes": { "maxLength": "10" } }, "field2": { "code": "not_null" } } } } }, "Workflow_APIs_token-introspection-request": { "title": "Token Introspection Request", "description": "An object representing a request to introspect the token related to a particular workflow request.", "type": "object", "required": [ "token" ], "properties": { "token": { "description": "The token that will be introspected.", "type": "string", "minLength": 1, "example": "eyJraWQiOiJqb3pubHp5ejRiZmg1b3l1ZGFxbmpppHYzbSIsInR5cCI6ImlkK0pXVCIsImFsZyI6IlJTMjU2In0.eyJhdF9oYXNoIjoicl82TklWQm9zSi0zOWQ3OGZTWlpppSIsInN1YiI6Im0zejR6NzQ1eG5oYWRhZjV6c2trZ2h1ZmptIiwiaWRwX25hbWUiOiJBcGl0b3BpYSIsImFtciI6WyJwd2QiXSwiaXNzIjoiaHR0cHM6XC9cL2Rhc2hib2FyZC1hcGl0b3BpYS5kZXYuYXBpdG9waWEuaW8iLCJub25jZSI6InVXV2Q2VC00NERBbmc4Wi1DcjVGdk1OWWNhd2NwSFRKdHNpdDFMbXJEWmciLCJhdWQiOiJuZnFzZDVxczRqZmx6a21oZTVhbWJraWVreSIsInRudF9pZCI6InFueTQ0dGdpN3ZmeDNjcG9tcXNjcmIyamN1IiwiYXV0aF90aW1lIjoxNjU5MzEwMjMwLCJleHAiOjE2NTkzMTIzMjcsImFwcF9pZCI6Im03azU1b25oNm5ic2pnZ2F5aHViYmVmNGVxIiwiaWF0IjoxNjU5MzEwNTI3LCJqdGkiOiJzc2JlMjdqemxuYmc1aXRmbG9saWMybHlnaSJ9.keMQpi25wcivhubJYtMSCiQkN2lXSRqXAw7FJB09naVS8XKHgELzLvM5cmzrzCcNSCRXk0LLdPJ1E5ATRVIkzJ6dLNR8RubF5Tijly6cp2R_9x2ziA94VyQDgO95BPg6HI6Oji9l3ruNYNwrJ-FAjZ1ZD8a_ZbunGo4HT2bXKVqFtEBM28Yf1u47wQsm4CxEwAa558X4Bq-bvkX8nccjlSEqq1TQLfP8hm0xMVH5mjwfBmbKkxoKPVxVKQKOx8RLX4xV4W0-uWl1dw3frquKLdzXGxGW0KYLNrQl_rT6V23DaZFuAIaLRJpppptqLNei2IoHciRR1HEUBwe3VzNx4A" } }, "x-examples": { "Example 1": { "value": { "token": "eyJraWQiOiJqb3pubHp5ejRiZmg1b3l1ZGFxbmpppHYzbSIsInR5cCI6ImlkK0pXVCIsImFsZyI6IlJTMjU2In0.eyJhdF9oYXNoIjoicl82TklWQm9zSi0zOWQ3OGZTWlpppSIsInN1YiI6Im0zejR6NzQ1eG5oYWRhZjV6c2trZ2h1ZmptIiwiaWRwX25hbWUiOiJBcGl0b3BpYSIsImFtciI6WyJwd2QiXSwiaXNzIjoiaHR0cHM6XC9cL2Rhc2hib2FyZC1hcGl0b3BpYS5kZXYuYXBpdG9waWEuaW8iLCJub25jZSI6InVXV2Q2VC00NERBbmc4Wi1DcjVGdk1OWWNhd2NwSFRKdHNpdDFMbXJEWmciLCJhdWQiOiJuZnFzZDVxczRqZmx6a21oZTVhbWJraWVreSIsInRudF9pZCI6InFueTQ0dGdpN3ZmeDNjcG9tcXNjcmIyamN1IiwiYXV0aF90aW1lIjoxNjU5MzEwMjMwLCJleHAiOjE2NTkzMTIzMjcsImFwcF9pZCI6Im03azU1b25oNm5ic2pnZ2F5aHViYmVmNGVxIiwiaWF0IjoxNjU5MzEwNTI3LCJqdGkiOiJzc2JlMjdqemxuYmc1aXRmbG9saWMybHlnaSJ9.keMQpi25wcivhubJYtMSCiQkN2lXSRqXAw7FJB09naVS8XKHgELzLvM5cmzrzCcNSCRXk0LLdPJ1E5ATRVIkzJ6dLNR8RubF5Tijly6cp2R_9x2ziA94VyQDgO95BPg6HI6Oji9l3ruNYNwrJ-FAjZ1ZD8a_ZbunGo4HT2bXKVqFtEBM28Yf1u47wQsm4CxEwAa558X4Bq-bvkX8nccjlSEqq1TQLfP8hm0xMVH5mjwfBmbKkxoKPVxVKQKOx8RLX4xV4W0-uWl1dw3frquKLdzXGxGW0KYLNrQl_rT6V23DaZFuAIaLRJpppptqLNei2IoHciRR1HEUBwe3VzNx4A" } } } }, "Workflow_APIs_expirationTime": { "description": "Time at which the request will expire.", "type": "string", "format": "date-time", "readOnly": true, "example": "2021-07-13T19:49:31.686Z" }, "Workflow_APIs_NewUserInvitationIntrospectionResponse": { "title": "New User Invitation Introspection Response", "description": "JSON Object representing a response to a new user invitation introspection request.", "type": "object", "x-tags": [ "Models" ], "properties": { "expirationTime": { "$ref": "#/components/schemas/Workflow_APIs_expirationTime" }, "newUserInvitationRequestId": { "description": "The ID of the new user invitation request.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 26, "example": "47jcm2ejayovsgbgbpkihblu4a" }, "tenantId": { "description": "The ID of the tenant associated to the request.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 26, "example": "x63nnomvwrgqhgd2ofpdt3uk5e" }, "applicationId": { "description": "The ID of the application associated to the request.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 26, "example": "hblu4a47jcm2ejayovsgbgbpki" }, "invitationType": { "description": "Enum representing the type of the invitation.", "type": "string", "readOnly": true, "enum": [ "EMAIL", "LINK" ], "minLength": 1, "maxLength": 45, "example": "EMAIL" }, "inviteeName": { "description": "The name of the person that the invite is intended for. This value will only be present for invitations of type `LINK`.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 60, "example": "Mike Jones" }, "email": { "description": "The email that the invitation was sent to. This value will only be present for invitations of type `EMAIL`.", "type": "string", "format": "email", "minLength": 1, "maxLength": 200, "example": "bob.smith@example.com" }, "rolesToAssign": { "description": "The list of role IDs specifying which roles will be assigned to the invited user.", "type": "array", "maxItems": 10, "uniqueItems": true, "items": { "description": "The ID of the role that will be assigned to the user.", "type": "string", "minLength": 1, "maxLength": 26, "example": "jayovsssgbgbpk47ihblujcm2e" }, "example": [ "jayovsssgbgbpk47ihblujcm2e" ] }, "status": { "description": "Enum representing the status of the new user invitation request.\n\n**Supported Status:**\n- `PENDING_INVITE_ACCEPTANCE`: The invitation is awaiting acceptance.\n- `PENDING_SESSION_CREATION`: The invitation has been accepted and a session can now be created for the invited user.\n- `CANCELED`: The invitation request has been cancelled.\n- `COMPLETED`: The invitation request has completed.", "type": "string", "readOnly": true, "enum": [ "PENDING_INVITE_ACCEPTANCE", "PENDING_SESSION_CREATION", "CANCELED", "COMPLETED" ], "minLength": 1, "maxLength": 60, "example": "PENDING_INVITE_ACCEPTANCE" }, "loginUrl": { "description": "The login URL that should be used for this request.", "type": "string", "format": "uri", "readOnly": true, "minLength": 1, "maxLength": 2000, "example": "http://example.com/login" }, "externalIdpRequestStatus": { "description": "The status of the external IdP request. This value will only be present for invites accepted using an external IdP.\n\n**Supported Statuses:**\n- `UNINITIALIZED`: The external IdP request has not been initialized.\n- `PENDING_EXTERNAL_IDP_AUTHORIZATION`: The request is awaiting the external IdP to authorize the user.\n- `USER_INFO_RETRIEVED`: The external IdP user's information has been retrieved.", "type": "string", "enum": [ "UNINITIALIZED", "PENDING_EXTERNAL_IDP_AUTHORIZATION", "USER_INFO_RETRIEVED" ], "readOnly": true, "minLength": 1, "maxLength": 60, "example": "PENDING_EXTERNAL_IDP_AUTHORIZATION" }, "externalIdpName": { "description": "The name of the external IdP that the invited user is associated to. Note, this value will only be present if the user attempted to signup with an external IdP.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 70, "example": "google" }, "externalIdpDisplayName": { "description": "The display name of the external IdP that the invited user is associated to. Note, this value will only be present if the user attempted to signup with an external IdP.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 20, "example": "Google" }, "externalIdpType": { "description": "The type of the external IdP that the invited user is associated to. Note, this value will only be present if the user attempted to signup with an external IdP.", "type": "string", "enum": [ "APPLE", "BITBUCKET", "CUSTOM", "GITHUB", "GITLAB", "GOOGLE", "GOOGLE_WORKSPACE", "MICROSOFT", "MICROSOFT_ENTRA_ID", "OKTA" ], "readOnly": true, "minLength": 1, "maxLength": 25, "example": "GOOGLE" }, "standardUserAttributesToSync": { "type": "array", "uniqueItems": true, "description": "List of standard user attributes that will be synced from the the external IdP.", "readOnly": true, "items": { "type": "string", "example": "email", "enum": [ "email", "fullName", "givenName", "familyName", "birthdate", "phoneNumber" ] } } }, "example": { "expirationTime": "2021-07-13T19:49:31.686Z", "newUserInvitationRequestId": "47jcm2ejayovsgbgbpkihblu4a", "status": "PENDING_INVITE_ACCEPTANCE", "tenantId": "x63nnomvwrgqhgd2ofpdt3uk5e", "applicationId": "hblu4a47jcm2ejayovsgbgbpki", "invitationType": "EMAIL", "inviteeName": null, "email": "bob.smith@example.com", "rolesToAssign": [ "jayovsssgbgbpk47ihblujcm2e" ], "loginUrl": "http://example.com/login", "externalIdpRequestStatus": "PENDING_EXTERNAL_IDP_AUTHORIZATION", "externalIdpName": "ent:google-workspace:org1", "externalIdpDisplayName": "Org 1", "externalIdpType": "GOOGLE_WORKSPACE", "standardUserAttributesToSync": [ "email", "fullName" ] } } }, "examples": { "Workflow_APIs_RequestBodyExample": { "value": { "token": "eyJraWQiOiJqb3pubHp5ejRiZmg1b3l1ZGFxbmpppHYzbSIsInR5cCI6ImlkK0pXVCIsImFsZyI6IlJTMjU2In0.eyJhdF9oYXNoIjoicl82TklWQm9zSi0zOWQ3OGZTWlpppSIsInN1YiI6Im0zejR6NzQ1eG5oYWRhZjV6c2trZ2h1ZmptIiwiaWRwX25hbWUiOiJBcGl0b3BpYSIsImFtciI6WyJwd2QiXSwiaXNzIjoiaHR0cHM6XC9cL2Rhc2hib2FyZC1hcGl0b3BpYS5kZXYuYXBpdG9waWEuaW8iLCJub25jZSI6InVXV2Q2VC00NERBbmc4Wi1DcjVGdk1OWWNhd2NwSFRKdHNpdDFMbXJEWmciLCJhdWQiOiJuZnFzZDVxczRqZmx6a21oZTVhbWJraWVreSIsInRudF9pZCI6InFueTQ0dGdpN3ZmeDNjcG9tcXNjcmIyamN1IiwiYXV0aF90aW1lIjoxNjU5MzEwMjMwLCJleHAiOjE2NTkzMTIzMjcsImFwcF9pZCI6Im03azU1b25oNm5ic2pnZ2F5aHViYmVmNGVxIiwiaWF0IjoxNjU5MzEwNTI3LCJqdGkiOiJzc2JlMjdqemxuYmc1aXRmbG9saWMybHlnaSJ9.keMQpi25wcivhubJYtMSCiQkN2lXSRqXAw7FJB09naVS8XKHgELzLvM5cmzrzCcNSCRXk0LLdPJ1E5ATRVIkzJ6dLNR8RubF5Tijly6cp2R_9x2ziA94VyQDgO95BPg6HI6Oji9l3ruNYNwrJ-FAjZ1ZD8a_ZbunGo4HT2bXKVqFtEBM28Yf1u47wQsm4CxEwAa558X4Bq-bvkX8nccjlSEqq1TQLfP8hm0xMVH5mjwfBmbKkxoKPVxVKQKOx8RLX4xV4W0-uWl1dw3frquKLdzXGxGW0KYLNrQl_rT6V23DaZFuAIaLRJpppptqLNei2IoHciRR1HEUBwe3VzNx4A" } }, "Workflow_APIs_NewUserInvitationIntrospectionResponse": { "description": "Basic example of a new user invitation introspection response JSON object.", "value": { "expirationTime": "2021-07-13T19:49:31.686Z", "newUserInvitationRequestId": "47jcm2ejayovsgbgbpkihblu4a", "status": "PENDING_INVITE_ACCEPTANCE", "tenantId": "x63nnomvwrgqhgd2ofpdt3uk5e", "applicationId": "hblu4a47jcm2ejayovsgbgbpki", "invitationType": "EMAIL", "inviteeName": null, "email": "bob.smith@example.com", "rolesToAssign": [ "jayovsssgbgbpk47ihblujcm2e" ], "loginUrl": "http://example.com/login", "externalIdpRequestStatus": "PENDING_EXTERNAL_IDP_AUTHORIZATION", "externalIdpName": "google", "externalIdpDisplayName": "Google", "externalIdpType": "GOOGLE" } } }, "requestBodies": { "Workflow_APIs_TokenIntrospectionRequestRequestBody": { "description": "Token Introspection Request JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow_APIs_token-introspection-request" }, "examples": { "Example 1": { "$ref": "#/components/examples/Workflow_APIs_RequestBodyExample" } } } } } } }, "x-tagGroups": [ { "name": "Workflow APIs", "tags": [ "Change Email", "Change Password", "Email Verification", "Existing User Invitation", "Login", "MFA Challenge", "Workflow APIs", "Workflow Request Object APIs", "MFA Enrollment", "New User Invitation", "Password Reset", "Signup", "Tenant Discovery", "User Activation" ] } ] } ```