Implementing Wristband Auth Endpoints
Learn how to implement the core Wristband authentication endpoints within your application.
To integrate with Wristband's user authentication flow, you'll need to implement the following three endpoints within your application: the Login Endpoint, the Callback Endpoint, and the Logout Endpoint.
Note
Where supported, you can use a Wristband SDK to handle all endpoint logic, eliminating the need to manually implement the API integration.
1. Login Endpoint
The Login Endpoint initiates a user authentication request by redirecting to the Wristband Authorization Endpoint.
Steps:
- Before redirecting to the Wristband Authorization Endpoint, the application should store any state that needs to be accessible in the Callback Endpoint. For example, if PKCE is being used, then the PKCE code verifier needs to be stored so that it can be passed to the Wristband Token Endpoint. Likewise, if deep linking is required, then a return URL also needs to be stored.
- Construct the authorization URL with the required parameters. The required parameters depend on the type of client making the authorization request. For example, a single-page application client must ensure that PKCE query parameters are included in the authorization request.
- Redirect the user to the Authorization Endpoint.
Wristband APIs to Call
- Authorization Endpoint: API Spec
Initiates the Authorization Code Flow for end users. Redirects users to the Wristband-hosted login page.
Preserving Login State
Before the Login Endpoint redirects to Wristband's Authorization Endpoint, certain state values must be persisted so that they can later be retrieved from the Callback Endpoint. Several methods can be used to persist the state values:
- Cookies
- Server-side cache (e.g., Redis)
- Local storage (SPA)
- In-memory storage (native apps)
Login Endpoint Query Parameters
Your application's login endpoint needs to support the following query parameters:
| Query Parameter | Type | Description |
|---|---|---|
| login_hint | string | A hint to Wristband about the user's preferred login identifier. This can be appended as a query parameter in the redirect request to the Wristband Authorization Endpoint. |
| return_url | string | The location of where to send users after authenticating. This value should be persisted so it can be retrieved later from the Callback Endpoint. |
| tenant_custom_domain | string | The custom domain of the tenant that the user belongs to. This value will only be present if the tenant has a custom domain defined. If this value is present, it should be used as the domain of the Wristband Authorization Endpoint URL. |
| tenant_domain | string | The domain name of the tenant the user belongs to. This value will only be present if the application's login URL does not use tenant subdomains. If the tenant_custom_domainvalue is not present; then this value should be used to construct the domain of the Wristband authorization endpoint URL. |
2. Callback Endpoint
The Callback Endpoint receives incoming calls from Wristband after the user has authenticated. If the user authenticated successfully, an authorization code will be passed to the Callback Endpoint. The Callback Endpoint can use the authorization code to retrieve an access token and refresh token from the Wristband Token Endpoint. After retrieving the access token, the Callback Endpoint can also call Wristband's UserInfo Endpoint to get information about the authenticated user. Finally, the Callback Endpoint needs to persist the tokens and any other session-related information before redirecting back to the application.
Steps:
- Use the state query parameter value to retrieve any persisted state values state values (e.g., PKCE code verifier).
- Exchange the authorization code for an access token and refresh token using the Wristband Token Endpoint.
- Establish an application session and redirect the user back to the application.
Wristband APIs to Call
- Token Endpoint: API Spec
Provides access tokens and refresh tokens for authenticated users.
- UserInfo Endpoint: API Spec
Provides additional user information about the authenticated user.
Callback Endpoint Query Parameters
Your application should have the ability to handle the following query parameters as part of a request to your Callback Endpoint:
| Query Parameter | Type | Description |
|---|---|---|
| code | string | The authorization code used to retrieve access and refresh tokens. |
| error | string | An error code indicating that an issue occurred during the login process. |
| error_description | string | A plaintext description giving more detail around the error that occurred. |
| state | string | The state value that was originally sent to the Wristband Authorization Endpoint. |
| tenant_custom_domain | string | If the tenant has a custom domain defined, then this query parameter will be part of the incoming request to the Callback Endpoint. If a redirect to the Login Endpoint is required, then this should be appended as a query parameter when redirecting to the Login Endpoint. |
| tenant_domain | string | The domain name of the tenant the user belongs to. If a redirect to the Login Endpoint is required, and neither tenant subdomains nor tenant custom domains are utilized, then this should be appended as a query parameter when redirecting to the Login Endpoint. |
3. Logout Endpoint
The Logout Endpoint is used to delete the application session and revoke any refresh tokens associated with the session. In addition, the Logout Endpoint must redirect to the Wristband Logout Endpoint to delete the user's authentication session within the Wristband platform. Afterwards, Wristband will redirect to the application's login URL (unless configured otherwise).
Steps:
- Destroy the application session.
- Revoke the refresh token (if applicable) using the Wristband Revoke Token Endpoint.
- Redirect the user to the Wristband Logout Endpoint.
Wristband APIs to Call
- Revoke Token Endpoint: API Spec
Revokes the specified refresh token.
- Logout Endpoint: API Spec
Terminates the Wristband authentication session for an end user. Redirects to the application login URL after clearing session data.
Refresh Token Flow
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 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 Type | Default | Description |
|---|---|---|
| Backend Server | Disabled | Servers don't require rotation for secure storage of secrets and tokens. |
| Native | Disabled | Native apps use secure storage methods. |
| Single Page App | Enabled | SPAs need rotation due to insecure client-side storage. |
Updated 1 day ago