Sessions and grants
The grant
At sign-in, auth-service issues a refresh token. The SDK stores it as the user's grant, keyed by the user's sub (the grant id). It is the only long-lived credential your backend holds for that user, so a GrantStore implementation should encrypt it at rest.
auth-service rotates the refresh token on every use: each refresh returns a new one that replaces the previous, and replaying a stale token revokes the whole family. A store therefore holds exactly one value per grant, and two refreshes of the same grant must never run at the same time.
GrantManager
GrantManager is the only place that refreshes tokens. It:
- serialises the refreshes of one grant through a
GrantLock(tasks of other grants run in parallel); - persists the rotated refresh token in the
GrantStoreafter each refresh, and keeps the stored one when the provider does not rotate; - mints access tokens per resource and caches them in memory until
expirySkewSeconds(30 by default) before they expire. Access tokens are never persisted; - drops the grant and throws
TOK_002when the user has no grant or the provider answersinvalid_grant. Only a new sign-in restores it. Other failures (network, server errors) keep the grant.
import { GrantManager, MemoryGrantStore, createAuthClient } from "@circle-rd/auth-ai";
const auth = createAuthClient({
issuer: "https://auth.example.com",
clientId: "my-app",
clientSecret: "<client-secret>",
redirectUri: "https://app.example.com/auth/callback",
});
const grants = new GrantManager({ auth, store: new MemoryGrantStore() });
// An access token for one audience (RFC 8707), valid for the resource only.
const { accessToken, expiresAt } = await grants.getAccessToken("user-sub", {
resource: "https://api.example.com",
});
Per-audience tokens
The sign-in asks for every audience in resources at once; the code exchange sends no resource, so the first token is valid for all of them. Each later refresh then narrows the new access token to the single resource you ask for. One refresh token, many narrow tokens: a token leaked from the gateway call cannot be replayed against your API.
| Audience | Used for | Minted by |
|---|---|---|
Your API URL (an entry of resources) | Bearer-protected routes of your own API | grants.getAccessToken(sub, { resource }) |
auth-service (issuer) | The user's wallet | ai.forUser(sub).wallet |
The gateway (gatewayUrl) | LLM and MCP calls | ai.forUser(sub).gateway |
With gatewayUrl set, the configuration adds the gateway URL and the issuer to resources and the wallet:self:read scope to scopes automatically.
scope on a refresh. The rotated refresh token would be left with the scopes of that request only, permanently stripping offline_access and the other scopes from the grant.Renewing claims
grants.refreshTokens(grantId) refreshes without narrowing to a resource and returns the whole TokenSet, ID token included. The sign-in handlers use it to renew a session's claims on a schedule (claimsRenewSeconds). Failures are those of getAccessToken.
Handling a refused token
If an API answers 401 to an access token, call grants.invalidate(grantId, resource) so the next getAccessToken mints a fresh one. The SDK's own clients (WalletClient, GatewayClient, the machine API) already do this.
Several replicas
The default lock, InProcessGrantLock, only serialises refreshes inside one process, and the access-token cache is per process too. With several replicas, pass a distributed GrantLock (or a row lock in your database) so two replicas never rotate the same grant at once. See Implement the stores.
Revoking
grants.revoke(grantId) revokes the refresh token at the provider, then forgets the grant even if the provider is unreachable: an outage must not keep the user signed in locally.
Architecture
The backend-for-frontend model: what the browser holds, what the server holds, and how a sign-in, a request and a sign-out flow through the SDK.
Entitlements
Roles, permissions, plan features and organisation from the user's claims, and the helpers that read them on the server and in the browser.