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.
What each token is
| Token | Form | Lifetime | Kept by Buun Identity |
|---|---|---|---|
| Access token | ES256 JWT, header typ: at+jwt, one aud | 15 minutes | No |
| ID token | ES256 JWT, header typ: JWT, aud is your client | 5 minutes | No |
| Refresh token | Opaque, buun_rt_ prefix | 30 days, a new one on every use | Its SHA-256 only |
| Authorization code | Opaque, buun_ac_ prefix | 60 seconds, used once | Its SHA-256 only |
Checking an access token
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
}
| Check | Why |
|---|---|
| Signature by a key in the JWKS, ES256 only | Anything else could be made by anyone |
typ is at+jwt | An ID token is never an access token |
iss is the issuer of your environment | A preview token never works in production |
aud is your own address, exactly | A token for another service opens nothing here |
exp has not passed | Tokens 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.