Skip to main content

​
Token types at a glance

​
Validating access tokens

Access tokens are JWTs signed with RS256. Validate them locally on every request — no per-request introspection round-trip to Busha.
1

Fetch and cache the JWKS

Fetch public keys from <issuer>/.well-known/jwks.json. Cache for ~5 minutes. Refetch when you encounter a kid (key ID) that is not in your cache.
Read the canonical issuer string from /.well-known/openid-configuration at startup and pin against it — do not hardcode.
2

Match the key and verify the signature

Match the JWT header’s kid to a key in the JWKS. Verify the RS256 signature with that key.
Never decode an unverified JWT and trust its claims. A forged token looks identical until you check the cryptographic signature.
3

Verify the standard claims

4

Enforce scopes on every endpoint

Check the scp claim (a space-separated string or array depending on your library) against the scope required by the endpoint being called. A token with scp="balances:read" cannot call a transfers endpoint.

​
Refreshing tokens

Every successful refresh issues a new (access_token, refresh_token) pair and immediately invalidates the old refresh token.
Rotation rules:
  • Persist the new pair atomically before discarding the old one. If persistence fails, you lose the session.
  • If a previously-rotated refresh token is replayed, Busha revokes the entire token family immediately.
  • Any invalid_grant response on a refresh is a hard disconnect — prompt the user to re-authorize.
  • The 30-day lifetime is sliding: each successful refresh resets the clock by another 30 days.

​
Revoking tokens

When a user disconnects your integration, revoke the refresh token:
The endpoint returns 200 with an empty body whether or not the token was valid — this is intentional and prevents leaking token validity.
Revoking a refresh token prevents future refreshes immediately, but does not invalidate a currently-issued access token. The access token continues to validate until its exp (~1 hour). For instant revocation on critical paths, consider maintaining a server-side allowlist that your backend checks.

​
Storage requirements

​
What never to log

Never write these values to application logs, request logs, or error trackers:
  • client_secret
  • access_token
  • refresh_token
  • code_verifier
  • Authorization code
  • id_token
Safe to log: client_id, jti, sub, scope list, request IDs, trace IDs.