Securing API Requests With Access Tokens

Learn how to secure your backend APIs using Wristband access tokens, including JWT signature verification, and token claim validation.

Overview

Access tokens provide a secure, stateless way to authenticate requests to your backend APIs. Wristband issues access tokens as JSON Web Tokens (JWTs), which can be included in the Authorization request header using the Bearer authentication scheme.

Using access tokens to authenticate API requests offers several benefits:

  1. Stateless Authentication: Access tokens contain claims about the authenticated user or machine, allowing backend APIs to validate requests without maintaining server-side session state.

  2. Cross-Domain Support: Access tokens can be used to authenticate requests across different domains without relying on browser cookies. For browser-based clients, the API must also be configured to allow the necessary cross-origin requests through CORS.

  3. Client Flexibility: Access tokens can be used by different types of clients, including web applications, mobile applications, and backend services.

Access Tokens Are Not a Replacement for Session Cookies

For applications that use a backend server, we recommend using session cookies to maintain authentication between the browser and your backend. Properly configured HttpOnly, Secure session cookies prevent client-side JavaScript from directly accessing session credentials and allow the backend to manage session expiration and revocation.

Access tokens are better suited for authenticating requests between services or to backend APIs that require token-based authentication. Your backend can securely store access tokens in the user's session and use them when calling protected APIs.

Access Token Validation

To secure your backend APIs using Wristband access tokens, you must validate each incoming token before processing the request.

This is typically handled by JWT validation middleware that performs the following steps:

  1. Extract the access token from the Authorization header.
  2. Verify the token's cryptographic signature.
  3. Validate the token's claims.

Once the token has been validated, your application can identify the authenticated user or machine and perform any additional authorization checks required to access the requested resource.

Extract the Access Token

The first step is to extract the access token from the incoming request's Authorization header.

The header must use the Bearer authentication scheme, with the access token provided after the Bearer keyword:

Authorization: Bearer <access_token>

If the header is missing, malformed, or does not contain a valid bearer token, the request should be rejected with a 401 Unauthorized response.

Verify the Token Signature

Wristband access tokens are JWTs consisting of three Base64URL-encoded components separated by dots (.):

<header>.<payload>.<signature>
  • Header: Contains metadata about the token, including its type, signing algorithm, and signing key identifier.
  • Payload: Contains claims describing the authenticated subject and other token metadata.
  • Signature: Cryptographically verifies the token's integrity and authenticity.

The following is an example JWT header for a Wristband access token:

{
  "kid": "qtott5t4fvau7lp3zk5dizbpju",
  "typ": "at+JWT",
  "alg": "RS256"
}

The header contains three important fields:

FieldDescription
kidIdentifies the public signing key used to verify the token's signature.
typIdentifies the token type. Wristband access tokens use at+JWT.
algIdentifies the signing algorithm. Wristband access tokens use RS256.

To verify an access token's signature:

  1. Decode the JWT header and verify that typ is at+JWT and alg is RS256.
  2. Retrieve the public signing key identified by kid from Wristband's JWKS Endpoint.
  3. Use the public key to verify the JWT signature using the RS256 algorithm.

The JWKS Endpoint exposes the public signing keys associated with your Wristband application. These keys can be cached locally to avoid retrieving them for every request. When caching the keys, set a reasonable expiration time so that keys that are rotated out don't stay in the cache forever.

Signature verification ensures the token was signed using a trusted key and has not been modified. However, a valid signature alone does not mean the token should be accepted. You must also validate its claims.

Use Wristband's JWT Validation SDKs

Rather than implementing JWT signature verification yourself, use one of Wristband's JWT Validation SDKs. These SDKs handle signature verification and help simplify the token validation process.

Validate Token Claims

After verifying the token's signature, your API must validate the claims contained in its payload.

At a minimum, validate the following claims:

ClaimValidation
iss (Issuer)Must exactly match the expected issuer URL for your Wristband application.
exp (Expiration)Must be later than the current time to ensure the token has not expired.

Issuer Validation (iss)

The iss claim identifies the Wristband application that issued the token. Your API must verify that its value exactly matches the expected issuer URL.

The issuer URL depends on your application's domain configuration:

  • Default Application Vanity Domain: If your application does not have an active custom domain, the issuer uses the default application vanity domain (e.g., https://yourapp-yourorg.us.wristband.dev).
  • Application Custom Domain: If your application has an active custom domain, the issuer uses that custom domain instead (e.g., https://auth.yourapp.com).

Your API should perform a strict string comparison against the expected issuer URL to ensure the token was issued by the correct Wristband application.

Expiration Validation (exp)

The exp claim specifies when the access token expires, represented as a Unix timestamp in seconds.

Your API must verify that the current time is earlier than the token's expiration time. Expired tokens must be rejected.

Additional Claim Validation

Depending on your application's security requirements, you may also want to validate additional claims:

ClaimDescription
app_idVerify that the token belongs to the expected Wristband application.
tnt_idVerify that the token is associated with a tenant the caller is authorized to access.
sub_kindVerify that the subject type (user, application_client, or tenant_client) is permitted to access the API.
client_idVerify that the token was issued to an authorized OAuth2 client, if your API restricts access to specific clients.

For more information about the claims contained in Wristband access tokens, see the JWTs and Signing Keys documentation.

If any required validation fails, your API should reject the request with a 401 Unauthorized response.


Did this page help you?