# 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

```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
}
```

| 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`](https://developers.buungroup.com/sign-in/plans) instead.

Source: https://developers.buungroup.com/sign-in/tokens
