Guides

Auth flows and diagrams

This section outlines the steps your application will follow for authenticating end users and machines, as well as the procedures for securely logging out.

Suggest Edits

Wristband APIs Your App Will Call

Authorize Endpoint

API Spec: Authorize Endpoint

Initiates the Authorization Code Flow for end users. Redirects users to the Wristband-hosted login page. Not for machine authentication.

Token Endpoint

API Spec: Token Endpoint

Provides access tokens for end users and machines. For end users, exchanges authorization codes for access tokens. For machines, uses the Client Credentials flow to obtain access tokens.

Userinfo Endpoint (Optional)

API Spec: User Info Endpoint

Provides additional user information after authentication. Enhances user experience by retrieving user details.

Revoke Token Endpoint

API Spec: Revoke Token Endpoint

Invalidates a refresh token to enhance security, especially during user logout.

Logout Endpoint

API Spec: Logout Endpoint

Terminates the authentication session for an end user. Redirects users to the Login page after clearing session data.


Endpoints to Implement in Your App

For end users, implement three endpoints: Login, Callback, and Logout. Machines do not require any additional endpoints.

Login Endpoint

Directs users to the Wristband Authorize Endpoint to start the login process.

Authorize URL with Tenant Vanity Domain

https://yourcustomer-yourb2bapp-yourcompany.us.wristband.dev/api/v1/oauth2/authorize

Preserving Login State

Use the state parameter to protect against CSRF attacks. Cache the state value for validation in the Callback endpoint. Methods include:

  • Cookies (HttpOnly and Secure)
  • Server-side cache (e.g., Redis)
  • Local storage (SPA)
  • In-memory storage (native apps)

Query Parameters To Handle

When using Wristband SDKs, the business logic for these query parameters is handled by the SDK for you.

Your application should have the ability to handle the following query parameters as part of a request to your Login Endpoint:

Query ParameterTypeDescription
login_hintstringA hint to Wristband about user's preferred login identifier. This can be appended as a query parameter in the redirect request to the Authorize URL.
return_urlstringThe location of where to send users after authenticating.
tenant_custom_domainstringThe tenant custom domain for the tenant that the user belongs to, if applicable. Should be used as the domain of the authorize URL when present.
tenant_domainstringThe domain name of the tenant the user belongs to. Should be used in the tenant vanity domain of the authorize URL when not utilizing tenant subdomains nor tenant custom domains.

Callback Endpoint

Handles the authorization code exchange for an access token.

Steps:

  1. Retrieve cached state values (e.g., code verifier).
  2. Validate the state parameter.
  3. Exchange the authorization code for an access token at the Token Endpoint.
  4. Establish an application session and redirect the user.

Query Parameters To Handle

When using Wristband SDKs, the business logic for these query parameters is handled by the SDK for you.

Your application should have the ability to handle the following query parameters as part of a request to your Callback Endpoint:

Query ParameterTypeDescription
codestringThe authorization code to use for exchanging for an access token.
errorstringAn error code indicating that some an issue occurred during the login process.
error_descriptionstringA plaintext description giving more detail around the issue that occurred during the login process.
statestringThe state value that was originally sent to the Authorize URL.
tenant_custom_domainstringIf the tenant has a tenant custom domain defined, then this query parameter will be part of the incoming request to the Callback Endpoint. n the event a redirect to the Login Endpoint is required, then this should be appended as a query parameter when redirecting to the Login Endpoint.
tenant_domainstringThe domain name of the tenant the user belongs to. In the event a redirect to the Login Endpoint is required and neither tenant subdomains nor tenant custom domains are not being utilized, then this should be appended as a query parameter when redirecting to the Login Endpoint.

Logout Endpoint

Logs out the user by destroying sessions and revoking tokens.

Logout URL with Tenant Vanity Domain

https://yourcustomer-yourb2bapp-yourcompany.us.wristband.dev/api/v1/logout?client_id=123

Additionally, ensure the correct tenant subdomain is used for multi-tenant applications. Extract the tenant subdomain from the URL or accept a tenant_domain query parameter.


Authorization Code Flow (End User Login)

The Authorization Code Flow is the primary OIDC flow for end users. Users are redirected to a Wristband-hosted Login page to authenticate and then redirected back to your application.

Backend Server

At a high level:

  1. The user clicks the Login button on your website or application.
  2. The user is sent to the Login Endpoint implemented by your backend server.
  3. The backend server creates an Authorization Request and redirects the user to the Wristband Authorize Endpoint.
  4. Wristband validates and records the Authorization Request and redirects the user to the Wristband-hosted Login page.
  5. The user provides their credentials to authenticate.
  6. The Login Page redirects to your application's Callback Endpoint with an authorization code.
  7. The Callback Endpoint calls Wristband's Token Endpoint to exchange the authorization code for an access token.
  8. The Callback Endpoint establishes an application session and sets a session cookie.
  9. The user is redirected to your application's entry point.

Password Login Flow

Single Page Application

At a high level:

  1. The user clicks the Login button on your website or application.
  2. The user is sent to the Login Route implemented in your SPA.
  3. The SPA creates an Authorization Request and redirects the user to the Wristband Authorize Endpoint.
  4. Wristband validates and records the Authorization Request and redirects the user to the Wristband-hosted Login page.
  5. The user provides their credentials to authenticate.
  6. The Login Page redirects to your SPA's Callback Route with an authorization code.
  7. The Callback function calls Wristband's Token Endpoint to exchange the authorization code for an access token.
  8. The Callback function stores the access token and refresh token in local storage.
  9. The user is redirected to your SPA's entry point.

Magic Link Login Flow

Native

At a high level:

  1. The user clicks the Login button within your native application.
  2. The native app creates an Authorization Request and sends the user to a browser for redirection to the Wristband Authorize Endpoint.
  3. Wristband validates and records the Authorization Request and redirects the user to the Wristband-hosted Login page.
  4. The user provides their credentials to authenticate.
  5. The Login Page redirects back to the native app's Callback Endpoint with an authorization code via deep linking.
  6. The Callback Endpoint calls Wristband's Token Endpoint to exchange the authorization code for an access token.
  7. The Callback Endpoint stores the access token and refresh token in secure storage.
  8. The user is redirected to your native app's entry point.

External IDP Login Flow

Refresh Token Flow (End Users)

To perform the Refresh Token Flow, an OAuth client sends a request to the Wristband Token Endpoint with the refresh token. Wristband validates the token and issues a new access token.

Refresh Token Flow

Refresh Token Rotation

Refresh token rotation enhances security by regularly changing the refresh token after each use. Wristband supports refresh token rotation for non-M2M clients. Defaults and recommendations:

Client TypeDefaultDescription
Backend ServerDisabledServers don't require rotation for secure storage of secrets and tokens.
NativeDisabledNative apps use secure storage methods.
Single Page AppEnabledSPAs need rotation due to insecure client-side storage.

Client Credentials Flow (M2M Client Authentication)

M2M clients use Client Credentials to obtain access tokens.

M2M Authentication

M2M Clients do not use refresh tokens. They reauthenticate directly with Wristband when access tokens expire.

Logout Flow

Logging out destroys user sessions, revokes tokens, and redirects the user to the Login page.

Backend Server

At a high level:

  1. The user clicks the Logout button within your application.
  2. The user is sent to the Logout endpoint of your backend server.
  3. The backend server destroys the session cookie.
  4. The backend server calls the Revoke Token Endpoint to revoke the refresh token.
  5. The user is redirected to the Wristband Logout Endpoint.
  6. Wristband destroys the authentication session and redirects the user to your application's Login endpoint.

Backend Server Logout Flow

Single Page Application

At a high level:

  1. The user clicks the Logout button within your SPA.
  2. The SPA invokes a logout() function, destroying the session and tokens in local storage.
  3. The SPA calls the Revoke Token Endpoint to revoke the refresh token.
  4. The user is redirected to the Wristband Logout Endpoint.
  5. Wristband destroys the authentication session and redirects the user to your SPA's Login route.

SPA Logout Flow

Native

At a high level:

  1. The user clicks the Logout button within your native app.
  2. The app invokes a logout() function, destroying tokens in secure storage.
  3. The app calls the Revoke Token Endpoint to revoke the refresh token.
  4. The user is redirected to the Wristband Logout Endpoint.
  5. Wristband destroys the authentication session and redirects the user to your app's Login screen via deep linking.

Native Logout Flow

Updated 29 days ago