---
updatedAt: 2026-06-04T19:57:42.000Z
agentTools:
projectIndex: https://docs.wristband.dev/llms.txt
---
# Create Auth Session For External IdP Login
### Redirect Required
Your application will need to redirect to this endpoint instead of making a direct API call.
### Tenant Vanity Domain Required
When calling this API you need to use the vanity domain of the tenant that the user is logging in to.
Creates an auth session for the external IdP login request. If the session is created successfully, this API redirects to the redirect URI specified in the authorization request with an authorization code and state (if provided). The response will also contain a session cookie associated with the authenticated user.
If the session creation fails, this API will redirect to the redirect URI specified in the authorization request with an error code.
# 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": "Login",
"description": "Login",
"x-displayName": "Login"
}
],
"paths": {
"/api/v1/external-idp-login/create-auth-session": {
"get": {
"summary": "Create Auth Session For External IdP Login",
"security": [],
"operationId": "createAuthSessionForExternalIdpLoginV1",
"servers": [
{
"url": "https://{tenant_vanity_domain}",
"description": "Wristband tenant scoped URL.",
"variables": {
"tenant_vanity_domain": {
"default": "tenant-yourapp-yourorg.us.wristband.dev",
"description": "Wristband vanity domain scoped to a specific tenant."
}
}
}
],
"tags": [
"Login"
],
"parameters": [
{
"$ref": "#/components/parameters/Workflow_APIs_AuthSessionCodeQueryParam"
}
],
"responses": {
"302": {
"description": "Found",
"headers": {
"Location": {
"description": "URI where the user will be redirected to after the creating the auth session.\n\nThe redirect URI that comes back from the API will point to the OAuth2 callback endpoint that was specified in the original authorization request:\n- If the call to the API is successful, the response will contain a session cookie. The redirect URI will also contain the following query parameters:\n - `code`: The newly created authorization code.\n - `state`: The original state value when the authorization request was started. This param will not appear if the authorization request never had state to begin with.\n- If an error occurs before the OAuth 2 redirect URL can be resolved during the processing of the request, then the redirect URI will point either to the Onboard error page URL by default or to a custom error page URL, if configured. It will also contain the following query parameters:\n - `error_code`: A code identifying the error that occurred.\n - `error_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.\n - `ticket`: Ticket that can help correlate the error to the backend.\n- If an error occurs after the OAuth 2 redirect URL can be resolved during the processing of the request, then the redirect URI will contain the following query parameters:\n - `error`: A code identifying the error that occurred.\n - `error_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.\n - `state`: The original state value when the authorization request was started. This param will not appear if the authorization request never had state to begin with.",
"schema": {
"type": "string",
"format": "uri"
},
"examples": {
"Example 1 - Auth Code Created": {
"description": "Redirect URI for a successful request.",
"value": "http://example.com/auth/callback?code=eyJraWQiOiJ3Skppp1lfWldPcmg3aFZJR1hTaTZidkozQmVqdlVYT3pPVm41My1RR1FjIiwidHlwIjoiYWMrSldUIiwiYWxnIjoiSFMyNTYifQ.eyJwYXJ0apppb24iOjUsImV4cCI6MTY1OTIxNzg4MiwianRpIjoibnQzemt5d3dpemQ3dHA2aTNpcmloZnB0cGUifQ.qo5PY_O1Su3HPpppW1VVdFWL83OKXNWxlOyUkc2fodg&state=Q0d3hY81cp_fBnk9libR1sOJ-rSJBUgfSzih4xkwvYs"
},
"Example 2 - Error Page URL": {
"description": "An error occurred before the OAuth2 redirect URL could be resolved during the processing of the request.",
"value": "http://example.com/error?error_code=INVALID_REQUEST&error_description=Prompt%20value%20%5BBAD%5D%20is%20not%20supported&ticket=11t7n71hi5e6t"
},
"Example 3 - Error with Resolved Redirect URI": {
"description": "An error occurred after the OAuth2 redirect URL was resolved during the processing of the request.",
"value": "http://example.com/auth/callback?state=Q0d3hY81cp_fBnk9libR1sOJ-rSJBUgfSzih4xkwvYs&error=INVALID_REQUEST&error_description=Prompt%20value%20%5BBAD%5D%20is%20not%20supported"
}
}
},
"Cache-Control": {
"$ref": "#/components/headers/Workflow_APIs_CacheControl"
},
"Pragma": {
"$ref": "#/components/headers/Workflow_APIs_Pragma"
},
"Set-Cookie": {
"$ref": "#/components/headers/Workflow_APIs_SetCookie"
}
}
},
"400": {
"$ref": "#/components/responses/Workflow_APIs_400-default"
},
"405": {
"$ref": "#/components/responses/Workflow_APIs_405"
},
"406": {
"$ref": "#/components/responses/Workflow_APIs_406"
},
"500": {
"$ref": "#/components/responses/Workflow_APIs_500"
},
"503": {
"$ref": "#/components/responses/Workflow_APIs_503"
}
}
}
}
},
"components": {
"parameters": {
"Workflow_APIs_AuthSessionCodeQueryParam": {
"name": "auth_session_code",
"description": "The auth session code that will be used to authorize the creation of the auth session.",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "eyJraWQiOiJlbjBPcW9HOU8zVzUxWno5TE1mN2RjMzlzaDJwYi13SDJLNWF4ZzVuUUc4IiwidHlwIjoic2MrSldUIiwiYWxnIjoiSFMyNTYifQ.eyJwYXJ0aXRpb24iOjEsImV4cCI6MTY1OTU2NjMxMiwianRpIjoiejdrNmU0YndxdmZleGt6YjZjcmJuY2ludG0ifQ.I3W1hbT0YqTG9ZFOTP4lToB_7Z1q30P8jsRxJ0UkSew"
}
}
},
"responses": {
"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_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-default": {
"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"
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"headers": {
"Workflow_APIs_CacheControl": {
"description": "Directive that controls caching in browsers and shared caches.\n\n**Supported Values:**\n- `no-store`: Indicates that the response may not be stored in any cache.",
"schema": {
"type": "string",
"enum": [
"no-store"
]
},
"example": "no-store"
},
"Workflow_APIs_Pragma": {
"description": "HTTP/1.0 general header is an implementation-specific header that may have various effects along the request-response chain. This header serves for backwards compatibility with the HTTP/1.0 caches that do not have a Cache-Control HTTP/1.1 header.\n\n**Supported Values:**\n- `no-cache`: Indicates that the response may not be stored in any cache.",
"schema": {
"type": "string",
"enum": [
"no-cache"
]
},
"example": "no-cache"
},
"Workflow_APIs_SetCookie": {
"description": "Used to send a cookie from the server to the user agent, so that the user agent can send it back to the server later. Wristband session cookies get both set and cleared from this header, depending on the API invoked.",
"schema": {
"type": "string"
},
"example": "sid=s:R1CR1K4ALGkySkGQMG3sCn7cgeeKUgFX.RJ6C4FUMxWGimQmYyiOHQRSxJwAvHq0Ad2v77NfLu0E; Path=/; Expires=Mon, 01 Aug 2021 08:11:40 GMT; HttpOnly; SameSite=Strict; Secure"
}
}
},
"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"
]
}
]
}
```