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 | Python type | Scope | Meaning |
|---|---|---|---|
roles | list[str] | None | roles | Roles the user holds in your application. |
permissions | list[str] | None | permissions | resource for read access, resource.write for write access. |
features | dict[str, str | int | float | bool] | None | features | Feature flags and limits of the user's plan. |
plan | str | None | — | The user's plan, when present. |
org_id | str | None | 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 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 whenrolesincludesrole.has_permission(claims, resource, action="read")checksresource.writefirst: write implies read, because auth-service keeps only the highest action. Read access isresourcealone.actionis"read"or"write".has_feature(claims, key)is true when the feature is present and is notFalse,0or"".get_feature(claims, key)returns the raw value (str | int | float | bool) orNone.
Where entitlements are read
| Where | How |
|---|---|
| Server, from the session | session.claims, from handlers.get_session(request) or the require_auth dependency. Claims are renewed every claims_renew_seconds. |
| Browser | GET /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 API | verified.claims of BearerVerifier(...).verify(token). |
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.
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 gateway_url, the wallet scope and the per-audience tokens let users call LLMs against their prepaid credit, and why the SDK has no debit API.