CIRCLE
Concepts

Sessions and grants

How one refresh-token chain per user becomes short-lived access tokens per audience, and why refreshes are serialised.

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 GrantStore after 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_002 when the user has no grant or the provider answers invalid_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.

AudienceUsed forMinted by
Your API URL (an entry of resources)Bearer-protected routes of your own APIgrants.getAccessToken(sub, { resource })
auth-service (issuer)The user's walletai.forUser(sub).wallet
The gateway (gatewayUrl)LLM and MCP callsai.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.

The SDK never sends 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.

Copyright © 2026