CIRCLE
Concepts

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.

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.

ClaimTypeScopeMeaning
rolesstring[]rolesRoles the user holds in your application.
permissionsstring[]permissionsresource for read access, resource.write for write access.
featuresRecord<string, string | number | boolean>featuresFeature flags and limits of the user's plan.
planstring—The user's plan, when present.
org_idstringorgThe 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 when roles includes role.
  • hasPermission(claims, resource, action = "read") checks resource.write first: write implies read, because auth-service keeps only the highest action. Read access is resource alone.
  • hasFeature(claims, key) is true when the feature is present and is not false, 0 or "".
  • getFeature(claims, key) returns the raw value (string | number | boolean) or undefined.

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

WhereHow
Server, from the sessionrequest.authSession.claims (Fastify) or handlers.getSession(request). Claims are renewed every claimsRenewSeconds.
BrowserGET /auth/me returns a SessionUser with roles, permissions, features normalised to empty values and plan and orgId when present.
Bearer-protected APIverified.claims of createBearerVerifier(...).verify(token).
Checks in the browser improve the interface; they are not a security boundary. Enforce every entitlement on the server, in the route that does the work.

SessionUser never carries tokens, sid or timestamps: those stay on the server.

Copyright © 2026