bluenexus.ai Get API Key

Token Lifecycle

How BlueNexus access tokens, refresh tokens, and sessions work — and how to manage them in your app.

Token Types

Token Purpose Lifetime Refreshable
Access Token API authentication ~15 minutes Via refresh token
Refresh Token Get new access tokens Configurable (days) Single-use, rotated
ID Token OpenID Connect identity ~1 hour Not refreshable
Personal Access Token Long-lived API access Configurable or no expiry No

Access Token Lifecycle

  1. Issued during OAuth token exchange (POST /v1/auth/token)
  2. Used in API requests via Authorization: Bearer <token>
  3. Expires after ~15 minutes (expires_in field in token response)
  4. Refreshed using the refresh token before or after expiry

Access tokens are JWT (RS256). You can verify them using the public keys at /.well-known/jwks.json, but for most use cases, just send them to the API and handle 401 responses.

Refresh Token Rotation

Refresh tokens are single-use. Each time you exchange a refresh token for a new access token, you get a new refresh token back:

curl -X POST https://api.bluenexus.ai/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=OLD_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

Response:

{
  "token_type": "Bearer",
  "access_token": "new-access-token",
  "expires_in": 900,
  "refresh_token": "new-refresh-token",
  "refresh_expires_in": 604800
}

Store the new refresh token immediately. The old one is invalidated.

If someone tries to reuse an old refresh token (replay attack), BlueNexus detects it and may invalidate the entire session for security.

Session Management

Each token pair is bound to an auth session. Sessions track:

  • When the token was last used
  • Which client issued the token
  • Provider permissions for that session

Revoking a session invalidates all tokens associated with it — no token blacklist needed.

Revocation

Revoke a Specific Token

curl -X POST https://api.bluenexus.ai/api/v1/auth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=TOKEN_TO_REVOKE" \
  -d "client_id=YOUR_CLIENT_ID"

Works with both access and refresh tokens.

Revoke a Session

curl -X DELETE https://api.bluenexus.ai/api/v1/auth-sessions/SESSION_ID/revoke \
  -H "Authorization: Bearer ACCESS_TOKEN"

Best Practices

  1. Refresh proactively — Don't wait for a 401. Track expires_in and refresh when ~80% of the lifetime has elapsed.

  2. Handle refresh failures gracefully — If a refresh fails, redirect the user through the OAuth flow again. Don't retry indefinitely.

  3. Store refresh tokens securely — They're as sensitive as passwords. Use encrypted storage, never log them, never expose them to client-side code.

  4. Implement retry on 401 — If an API call returns 401, try refreshing the token once and retrying the request. If the refresh also fails, redirect to re-authorize.

  5. Don't decode access tokens for auth decisions — Treat them as opaque strings. Use the API to validate permissions, not JWT claims.

Next Steps