Site Home
API Reference
LoginTry for Free

Authorize

get
https://{application_vanity_domain}/api/v1/oauth2/authorize
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

↪️

Redirect Required

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

🛡️

OIDC Compliant

This endpoint is compliant with the OIDC Authorization Endpoint (Authorization Code Flow) specification.

Initiates the OIDC Authorization Code flow. This API can be called using either an application vanity domain or a tenant vanity domain. The API's behavior depends on which vanity domain is used in the request, as described below.

Note

An application vanity domain can only be used when application authorization requests are enabled for the application.

If an Application Vanity Domain Is Used

Initiates an application-level login request. If the request is valid, the user is redirected to either the Wristband-hosted application login page or a custom application login page, if configured.

On the login page, the user completes the tenant discovery flow to identify the tenant they want to log in to. Once the tenant is resolved, the user is redirected to the authorize endpoint using the tenant's vanity domain to initiate the tenant-level login flow.

If the request is invalid, the user is redirected to either the default Wristband application error page or a custom application error page, if configured.

Note

When the user is redirected to an application login page, an authorization request JWT containing the original authorization request parameters is created and appended to the URL as the req query parameter. The login page can use this JWT to retrieve the original authorization request parameters by calling the Introspect Authorization Request Token API.

If a Tenant Vanity Domain Is Used

Initiates a login request for a specific tenant. The tenant vanity domain identifies the tenant the user is attempting to log in to. When this endpoint is invoked, one of the following actions occurs:

  • Invalid request with an undeterminable redirect URI or invalid client ID: The user is redirected to either the default Wristband tenant error page or a custom tenant error page, if configured.

  • Invalid request with a valid client redirect URI: The user is redirected to the client's redirect URI with the appropriate error code.

  • Valid request with an unauthenticated user: If a valid authentication session cookie is not present, the user is redirected to either the Wristband-hosted tenant login page or a custom tenant login page, if configured. This behavior applies when the prompt parameter is omitted or set to login. If prompt is set to none, the user is redirected to the client's redirect URI with a login_required error code.

  • Valid request with an authenticated user and prompt=login: The user is redirected to either the Wristband-hosted tenant login page or a custom tenant login page, if configured, to initiate a new login flow.

  • Valid request with an authenticated user and prompt=none or an omitted prompt parameter: The user is redirected to the client's redirect URI with an authorization code.

Note

When the user is redirected to a tenant login page, an authorization request JWT containing the original authorization request parameters is created and appended to the URL as the req query parameter. The login page can use this JWT to retrieve the original authorization request parameters by calling the Introspect Authorization Request Token API.

Error Codes:

Below is a list of error codes that can be returned on redirects to the client's callback URI.

  • invalid_request: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
  • unauthorized_client: The client is not authorized to request an authorization code, usually because the client doesn't support the authorization_code grant type.
  • access_denied: The resource owner or authorization server denied the request.
  • unsupported_response_type: The response type specified in the request is not supported.
  • invalid_scope: The requested scope is invalid, unknown, or malformed.
  • server_error: The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
  • temporarily_unavailable: The authorization server is currently unable to handle the request due to a temporary overload or maintenance of the server.
  • login_required: The authorization request does not have a valid auth session associated with it and requires the user to authenticate.
  • request_not_supported: Returned if the OIDC request parameter is specified in the request.
  • request_uri_not_supported: Returned if the OIDC request_uri parameter is specified in the request.
  • registration_not_supported: Returned if the OIDC registration parameter is specified in the request.
Query Params
string
required
length between 1 and 26

ID of the client initiating the authorization request.

string
enum
required
length ≥ 1

The response type that the client is requesting. This will affect the response that is returned from the authorization request.

Supported Values:

  • code: The authorization code will be returned as the code query parameter when redirecting to the registered callback endpoint.
Allowed:
uri
length between 1 and 2000

The redirect URI that will be used to send the authorization code or authorization errors back to the client. The redirect URI value must exactly match one of the redirect URIs registered with the client initiating the request. If the client requesting authorization only has one redirect URI registered with Wristband, then the redirect_uri query parameter can be omitted.

Note: When a redirect URI is registered with the {tenant_name} placeholder, pass the URI to the Authorize endpoint exactly as registered. Do not substitute {tenant_name} with an actual tenant name. For example: redirect_uri=https://{tenant_name}.myapp.com/auth/callback.

string
length between 22 and 512

An opaque value used by the client to maintain state between the request and callback. When Wristband redirects to the callback endpoint it will include the original state value in the state query parameter.

string
length between 22 and 128

An opaque value used to associate the authorization request with an ID Token. The value is passed through unmodified from the authentication request to the ID Token. If present in the ID Token, clients MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authorization request before trusting claims included in the ID token.

string
required
length between 1 and 1000

The authorization and token endpoints allow the client to specify the scope of the authorization request using the scope request parameter. In turn, the authorization server uses the scope response parameter to inform the client of the scopes of the access token issued. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional requested scope.

Supported Scopes:

  • openid - Required for OIDC requests.
  • profile - Includes the following claims in the User Info response: name, given_name, family_name, middle_name, nickname, preferred_username, picture, gender, birthdate, zoneinfo, locale, updated_at
  • email - Includes the following claims in the User Info response: email, email_verified
  • phone - Includes the following claims in the User Info response: phone_number, phone_number_verified
  • roles - Includes the following claims in the User Info response: roles
  • offline_access - If specified the response from the Token Endpoint will return a refresh token along with the access token.

Required Scopes:

  • openid
string
length between 43 and 128
[A-Za-z0-9-._~]

This field is used by clients to implement the Proof Key for Code Exchange (PKCE) extension of the OAuth 2 specification. The client first creates a code challenge which is sent to the server when requesting authorization. The client then uses the code verifier (the string used to create the code challenge) when exchanging the authorization code for an access token. In OAuth 2.1 it is required that clients use PKCE unless the following conditions are met:

  1. The client is a confidential client.
  2. In the specific deployment and the specific request, there is reasonable assurance by the authorization server that the client implements the OpenID Connect nonce mechanism properly.

Therefore, if the client is a confidential client and the nonce query parameter is specified, then the code_challenge query parameter is not required; otherwise, the code_challenge is required.

string
enum
length ≥ 1

The method used for creating the code challenge. If the code_challenge query parameter is present in the authorization request, then the code_challenge_method is required; otherwise, it is not required.

Supported Methods:

  • S256: The code challenge is a BASE64-URL-encoded string of a SHA256 hash of the code verifier.
Allowed:
string
enum
length ≥ 1

Specifies whether the server should prompt the end user for re-authentication.

Supported Prompts:

  • none: The Authorization Server MUST NOT prompt the user to authenticate. If the user does not already have an authenticated session then a login_required error is returned.
  • login: The Authorization Server will always prompt the user to authenticate, even if the user already has an authenticated session.

Prompt is not a required field. If it's not specified as part of an authorization request, then the default behavior is as follows:

  • If a valid auth session cookie is present, then an authorization code will automatically be created, and the user will be redirected to the callback endpoint without having to re-authenticate.
  • If an auth session cookie is not present or invalid, then the user is redirected to the login page to authenticate.
Allowed:
integer
≥ 1

Specifies the allowable elapsed time in seconds since the last time the user was actively authenticated. If the elapsed time is greater than this value, the user must re-authenticate, even if they already have a valid auth session.

string
length between 1 and 200

Hint about the login identifier the end-user might use to log in. If provided, this value will be used to pre-populate the login identifier form field. Note, if a login hint value is provided and an existing auth session is detected, one of the login identifiers (email or potentially username if it's configured as a login identifier) for the user associated with the auth session must match the login hint value; otherwise, the existing auth session will be revoked and the user will have to login again.

string
length between 1 and 100

Hint indicating which Identity Provider (IdP) the user should authenticate with. The value must match the name of an IdP enabled for the user's tenant. If a match is found, the user is automatically taken to that IdP's login page. If no match is found, then the IdP hint is ignored and the regular login page is shown.

string
length between 1 and 63

Hint identifying the tenant the user is trying to log in to. This query parameter is evaluated only when the authorization request uses an application vanity domain; otherwise, it is ignored. The value must match the name of an active tenant within the application identified by the application vanity domain. If a matching tenant is found, the user is automatically redirected to that tenant's login page. Otherwise, the hint is ignored, and the user must complete the tenant discovery workflow.

string

JWT containing the authorization request parameters. Use this parameter only to propagate an application-level authorization request token to a tenant-level authorization request.

Cookie Params
Responses

Updated 1 day ago

Did this page help you?
Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
*/*
application/json

Updated 1 day ago

Did this page help you?