Authorize

get

https://{tenant_vanity_domain}/api/v1/oauth2/authorize

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

↪️
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.

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

Initiates a user login request for a specific tenant. The tenant vanity domain in the request identifies the tenant the user is logging into. When this endpoint is redirected to, one of the following responses will be returned:

If the request fails and the client's redirect URI can't be determined or the client ID is invalid, this API returns a redirect to either the default Wristband error page or a custom error page, if one is configured.
If the given request fails and the client's redirect URI is valid, then this API returns a 302 redirect to the client's redirect URI with the appropriate error code.
If the request is valid but the user is not authenticated (i.e., a valid auth session cookie is not present), the user will be redirected to either the Wristband-hosted login page or a custom login page, if configured. The prompt param must also either be set to login or not be set at all. If the prompt param is set to none then a 302 redirect to the client's redirect URI will be returned with a login_required error code.
If the request is valid and the user is authenticated (i.e., a valid auth session cookie is present), but the prompt param is set to login, then the user will be redirected to either the Wristband-hosted login page or a custom login page, if one is configured.
If the request is valid and the user is authenticated (i.e., a valid auth session cookie is present) and the prompt query param is set to none, or is not set at all, then this API will return a redirect to the client's redirect URI with an authorization code.

ℹ️
Note
If a response is returned that redirects to a login page, then an authorization request JWT will be created (composed of the original authorization request parameters) and appended to the URL using the req query parameter. The authorization request JWT can then be used by the login page to infer the original authorization request parameters by introspecting the JWT using 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

client_id

string

required

length between 1 and 26

ID of the client initiating the authorization request.

response_type

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:

redirect_uri

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.

state

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.

nonce

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.

scope

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

code_challenge

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:

The client is a confidential client.
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.

code_challenge_method

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:

prompt

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:

max_age

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.

login_hint

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.

idp_hint

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.

Responses

Redirect Required

Tenant Vanity Domain Required

OIDC Compliant

Note

302Found

400Bad Request

405Method Not Allowed

406Not Acceptable

500Internal Server Error

503Service Unavailable