Token Model
Last updated
go-jwt manages a login session with three credentials: a short-lived Access Token, a long-lived Refresh ID, and a JTI whitelist stored in Redis.
Three Credentials
| Credential | Form | Default lifetime | Where it lives | Purpose |
|---|---|---|---|---|
| Access Token | ES256-signed JWT | 15 minutes (AccessTokenExpires) | Cookie access_token, or Authorization: Bearer | Authenticate every request |
| Refresh ID | 64-character hex string (SHA-256) | 7 days (RefreshIdExpires) | Cookie refresh_id, or X-Refresh-ID header | Obtain a new token when the Access Token expires |
| JTI | UUID v4 | Same as the Access Token | Redis jti:<jti> | Let the server invalidate an issued Access Token |
The Refresh ID carries no data; it is the key of Redis
refresh:<id>. User data, version, and device fingerprint live server-side in RefreshData.Access Token Claims
Claims written by
signJWT():| Claim | Source |
|---|---|
id, name, email, thumbnail, scope, role, level | Auth fields |
fp | Device fingerprint of this request |
jti | Newly generated UUID |
exp | Issue time + AccessTokenExpires |
iat, nbf | Issue time |
refresh_id (name taken from RefreshIdCookieKey) | Bound Refresh ID |
A JWT is signed, not encrypted; anyone holding it can decode every
Auth field, so keep sensitive data out.How the Refresh ID Is Derived
createRefreshId() serializes {id, name, email, fp, iat, jti} to JSON, hashes it with SHA-256, and outputs hex. Because it includes jti and the current time, each login yields a different Refresh ID for the same user.RefreshData
The value of Redis
refresh:<id>:| Field | Description |
|---|---|
data | Auth |
version | 1 at issue, +1 per refresh; the pair is fully reissued once it exceeds MaxVersion |
fp | Device fingerprint at issue; must match on refresh |
exp, iat | Times of the first issue; kept unchanged on refresh |
jti | JTI of the most recent issue |
Session Lifecycle
| Stage | Trigger | Page |
|---|---|---|
| Issue | The application calls Create() | API Reference |
| Verify | Every request, via Verify() or middleware | Verification Flow |
| Refresh | Access Token expired or missing while the Refresh ID is still valid | Transparent Refresh |
| Revoke | The application calls Revoke() | Revocation |