Buun Group Developers
Pages

Tokens and keys

Every access token and ID token is a JWT signed with ES256 by Buun Identity. A product checks one with the published keys, without calling the issuer.

Markdown

What each token is

TokenFormLifetimeKept by Buun Identity
Access tokenES256 JWT, header typ: at+jwt, one aud15 minutesNo
ID tokenES256 JWT, header typ: JWT, aud is your client5 minutesNo
Refresh tokenOpaque, buun_rt_ prefix30 days, a new one on every useIts SHA-256 only
Authorization codeOpaque, buun_ac_ prefix60 seconds, used onceIts SHA-256 only

Checking an access token

ts
import { createRemoteJWKSet, jwtVerify } from 'jose'


const issuer = 'https://id.buungroup.com'
const keys = createRemoteJWKSet(new URL('/.well-known/jwks.json', issuer), { timeoutDuration: 5000 })


export async function verify(token: string, audience: string) {
  const { payload } = await jwtVerify(token, keys, { issuer, audience, typ: 'at+jwt', algorithms: ['ES256'], clockTolerance: 30 })
  return payload
}
CheckWhy
Signature by a key in the JWKS, ES256 onlyAnything else could be made by anyone
typ is at+jwtAn ID token is never an access token
iss is the issuer of your environmentA preview token never works in production
aud is your own address, exactlyA token for another service opens nothing here
exp has not passedTokens are short on purpose

Keys and rotation

The keys are at /.well-known/jwks.json, cached for a while by the issuer's headers. When the issuer rotates, the old key stays published until every token it signed has ended. jose reads the set again when it meets a kid it does not know, so a rotation needs nothing from you.

What a token never holds

A plan, a price, or anything about what the person pays. Ask /oauth/plans instead.