---
updatedAt: 2026-06-04T19:57:42.000Z
agentTools:
  projectIndex: https://docs.wristband.dev/llms.txt
---

# Create Auth Session for External IdP User

<br />

<Callout icon="↪️" theme="default">
  ### Redirect Required

  Your application will need to redirect to this endpoint instead of making a direct API call.
</Callout>

<Callout icon="🏢" theme="default">
  ### Tenant Vanity Domain Required

  When calling this API you need to use the vanity domain of the tenant that the user belongs to.
</Callout>

Creates a new auth session for the user and returns a response containing a redirect to the configured redirect location.  The response will also include the session cookie.

The redirect URL that gets returned will resolve in the following order:

* If a Signup Workflow custom redirect URL is configured, that will be returned.
* If a client ID is passed to the signup request and a client login URL is defined, it will be returned.
* Otherwise, the application login URL is returned.

# 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": "Signup",
      "description": "Signup",
      "x-displayName": "Signup"
    }
  ],
  "paths": {
    "/api/v1/external-idp-signup/create-auth-session": {
      "get": {
        "summary": "Create Auth Session for External IdP User",
        "security": [],
        "operationId": "createExternalIdpUserAuthSessionV1",
        "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": [
          "Signup"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Workflow_APIs_AuthSessionCodeQueryParam"
          }
        ],
        "responses": {
          "302": {
            "$ref": "#/components/responses/Workflow_APIs_302-auth-session-created"
          },
          "400": {
            "$ref": "#/components/responses/Workflow_APIs_400-default"
          },
          "403": {
            "$ref": "#/components/responses/Workflow_APIs_403"
          },
          "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_403": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Workflow_APIs_api-error"
            },
            "examples": {
              "code - unauthorized": {
                "value": {
                  "type": "base_error",
                  "code": "unauthorized",
                  "message": "The request failed authorization",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "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"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Workflow_APIs_302-auth-session-created": {
        "description": "Found",
        "headers": {
          "Location": {
            "description": "URI where the user should be redirected to in order to establish their auth session.",
            "schema": {
              "type": "string",
              "format": "uri",
              "minLength": 1
            },
            "examples": {
              "Example 1 - Auth Session Created": {
                "description": "The resolved redirect URI upon successful auth session creation.",
                "value": "http://example.com/login"
              }
            }
          },
          "Cache-Control": {
            "$ref": "#/components/headers/Workflow_APIs_CacheControl"
          },
          "Pragma": {
            "$ref": "#/components/headers/Workflow_APIs_Pragma"
          },
          "Set-Cookie": {
            "$ref": "#/components/headers/Workflow_APIs_SetCookie"
          }
        }
      }
    },
    "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"
      ]
    }
  ]
}
```