Entitlements
auth-service puts the user's entitlements for your application into the ID token (and into JWT access tokens). A claim is present only when its scope was granted, which is why the SDK requests roles, permissions and features by default.
| Claim | Type | Scope | Meaning |
|---|---|---|---|
roles | string[] | roles | Roles the user holds in your application. |
permissions | string[] | permissions | resource for read access, resource.write for write access. |
features | Record<string, string | number | boolean> | features | Feature flags and limits of the user's plan. |
plan | string | — | The user's plan, when present. |
org_id | string | org | The organisation, when the scope is granted. |
The claims model is documented in auth-service: OIDC claims and Roles and permissions (RBAC). The org scope is not in the SDK's default scopes: add it to scopes if you need org_id.
Helpers
Four pure functions read these claims. They accept any object with roles, permissions and features: the ID token claims on the server, a SessionUser in the browser.
import { getFeature, hasFeature, hasPermission, hasRole } from "@circle-rd/auth-ai";
import type { IdTokenClaims } from "@circle-rd/auth-ai";
function describe(claims: IdTokenClaims) {
return {
admin: hasRole(claims, "admin"),
canWriteReports: hasPermission(claims, "reports", "write"),
canReadReports: hasPermission(claims, "reports"),
beta: hasFeature(claims, "beta"),
seats: getFeature(claims, "seats"),
};
}
hasRole(claims, role)is true whenrolesincludesrole.hasPermission(claims, resource, action = "read")checksresource.writefirst: write implies read, because auth-service keeps only the highest action. Read access isresourcealone.hasFeature(claims, key)is true when the feature is present and is notfalse,0or"".getFeature(claims, key)returns the raw value (string | number | boolean) orundefined.
The same helpers are exported from @circle-rd/auth-ai/client, and useEntitlements() in the React and Vue bindings wraps them for the current user.
Where entitlements are read
| Where | How |
|---|---|
| Server, from the session | request.authSession.claims (Fastify) or handlers.getSession(request). Claims are renewed every claimsRenewSeconds. |
| Browser | GET /auth/me returns a SessionUser with roles, permissions, features normalised to empty values and plan and orgId when present. |
| Bearer-protected API | verified.claims of createBearerVerifier(...).verify(token). |
SessionUser never carries tokens, sid or timestamps: those stay on the server.
Sessions and grants
How one refresh-token chain per user becomes short-lived access tokens per audience, and why refreshes are serialised.
Credit wallet and LiteLLM gateway
How gatewayUrl, the wallet scope and the per-audience tokens let users call LLMs against their prepaid credit, and why the SDK has no debit API.