Login

Steps:

1. The user clicks the Login button within your application.
2. The user is sent to the Login Endpoint hosted on your backend server.
3. The backend server creates an Authentication Request and redirects the user to the Wristband Authorization Endpoint.
4. Wristband processes the Authentication Request and redirects the user to the Wristband-hosted Login Page for your application.
5. The user provides their credentials to authenticate.
6. After the user has authenticated, Wristband 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 a set of tokens. The Token Endpoint will always return an access token and ID token for the authenticated user. A refresh token will also be returned if the offline_access scope was passed in the initial request to the Authorization Endpoint.
8. The Callback Endpoint uses the user's access token to call Wristband's User Info Endpoint to get the user's claims. The claims that are returned are determined by the scopes that were specified in the initial request to the Authorization Endpoint.
9. The Callback Endpoint creates the user's Application Session, which in this case is stored within a cookie.
10. The user is redirected to your application's home page or a specified deep link.

Logout

Steps:

1. The user clicks the Logout button within your application.
2. The user is sent to the Logout Endpoint hosted on your backend server.
3. The backend server destroys the user's Application Session cookie.
4. If a refresh token was created for the user (i.e., the offline_access scope was specified), the backend server calls Wristband's Revoke Token Endpoint to revoke the refresh token.
5. The user is redirected to Wristband's Logout Endpoint to destroy Wristband's Auth Session.
6. Wristband destroys the Auth Session and redirects the user to your application's Login Endpoint, or a specified redirect URL.

Refreshing Access Tokens

Steps:

1. The client-side application sends a request to any protected API on the backend server. The session cookie is automatically included in the request headers.
2. Before reaching the business logic of the requested route, an authentication middleware processes the request. The middleware accesses the user's session data, which includes the access token, refresh token, and access token expiration time.
3. The middleware checks if the access token has expired. If the access token has expired, the middleware makes a request to Wristband's Token Endpoint to retrieve a new access token. In order for the request to succeed, the refresh token from the user's session must be included in the request body.
4. Wristband verifies the refresh token's validity. If valid, it generates a new access token and includes it in the response.
5. After obtaining a valid access token, the middleware allows the protected API to proceed with its business logic. In addition, the session is updated to include the new access token and access token expiration time.

Handling Refresh Failures

The token refresh operation can fail for the following reasons:

• The refresh token has expired.
• The refresh token has been revoked.
• The refresh token has been tampered with and is no longer valid.
• Network issues or server errors (e.g.: 500 Internal Server Error).

⚠️

Retrying Refresh Requests

For 500 errors, it is advised to retry the refresh request to minimize disruption for the end user. We recommend implementing retry logic with an exponential backoff.

Server-side Error Handling

If the call to Wristband's Token Endpoint fails, and the error can't be recovered from using retries, then the backend server should perform the following actions.

1. Invalidate the user's session by doing the following:
   1. Cookie-based sessions: Clear the session cookie and set it to expire immediately.
   2. Server-side sessions: Clear the session cookie and set it to expire immediately. In addition, remove the session data from the backend session store.
2. Return an appropriate error response to the client. The error response should use a 401 Unauthorized status code to indicate that the user is no longer authenticated.

Client-side Error Handling

When the client-side application receives a 401 response from the server, you can handle it in various ways based on your UX and security requirements:

1. Redirect to Login Without Destroying the Wristband Auth Session: Send the user to the Wristband login page without calling the Wristband Logout Endpoint. If the user still has a valid Wristband Auth Session, they will automatically be re-authenticated without having to enter their credentials.
2. Full Logout and Re-authentication: Clean up any local session data from the client-side application, then redirect the user to Wristband’s Logout Endpoint to terminate the Wristband Auth Session. This will force the user to re-authenticate the next time they try to access your application.