CIRCLE
Concepts

Entitlements

Roles, permissions, plan features and organisation from the user's claims, and the helpers that read them on the server.

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.

ClaimPython typeScopeMeaning
roleslist[str] | NonerolesRoles the user holds in your application.
permissionslist[str] | Nonepermissionsresource for read access, resource.write for write access.
featuresdict[str, str | int | float | bool] | NonefeaturesFeature flags and limits of the user's plan.
planstr | None—The user's plan, when present.
org_idstr | NoneorgThe 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 attributes: IdTokenClaims and AccessTokenClaims on the server, or a SessionUser.

from auth_ai import IdTokenClaims, get_feature, has_feature, has_permission, has_role


def describe(claims: IdTokenClaims) -> dict[str, object]:
    return {
        "admin": has_role(claims, "admin"),
        "can_write_reports": has_permission(claims, "reports", "write"),
        "can_read_reports": has_permission(claims, "reports"),
        "beta": has_feature(claims, "beta"),
        "seats": get_feature(claims, "seats"),
    }
  • has_role(claims, role) is true when roles includes role.
  • has_permission(claims, resource, action="read") checks resource.write first: write implies read, because auth-service keeps only the highest action. Read access is resource alone. action is "read" or "write".
  • has_feature(claims, key) is true when the feature is present and is not False, 0 or "".
  • get_feature(claims, key) returns the raw value (str | int | float | bool) or None.

Where entitlements are read

WhereHow
Server, from the sessionsession.claims, from handlers.get_session(request) or the require_auth dependency. Claims are renewed every claims_renew_seconds.
BrowserGET /auth/me returns the user as a SessionUser in camelCase JSON, with roles, permissions, features normalised to empty values and plan and orgId when present.
Bearer-protected APIverified.claims of BearerVerifier(...).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. to_session_user(claims) builds it from an IdTokenClaims, and user.to_json() gives the camelCase dictionary (emailVerified, orgId) without the empty optional members.

Copyright © 2026