Authentication

Cessy uses explicit authentication at each surface. The caller’s token determines tenant, app, scope, actor, and allowed operations.

Web interface language

The Cessy web interface currently supports English and German for the core sign-in, registration, account, and Operate flows. Users can change the language from the authentication pages or account menu without changing the current URL.

Cessy remembers the selection in a secure, path-wide cookie. When no selection exists, it uses the browser’s preferred language if supported and otherwise falls back to English. Authentication errors shown in the interface are mapped from stable application error codes; raw identity-provider messages and query parameters are never rendered as trusted user-facing copy.

Registration uses the same password contract in the browser and on the server, and shows that requirement before submission. While account creation is in flight, the form is single-flight and cannot be submitted again. When email confirmation is required, registration ends on a dedicated check-inbox screen; the recent result is retained for back or refresh navigation in the same browser tab. Identity-provider email rate limits are presented as inbox-first guidance with a short local retry cooldown. This browser receipt improves continuity but does not claim server-side signup idempotency.

Password recovery follows the same interaction contract. The request form does not reveal whether an address has an account, changes to a dedicated check-inbox screen after a successful request, and retains that recent result in the same browser tab. Resend is single-flight and locally rate limited, with explicit inbox and spam-folder guidance. The new-password form shows the active minimum length before submission, offers focus-preserving visibility controls, and returns focus to the field that needs correction. After a successful update, the recovery session is signed out and the user returns to sign in with the new password. Expired, already-used, or otherwise invalid recovery links lead to a dedicated state with a safe action for requesting a replacement link.

The locale is resolved from request cookies and headers at the application root. Under Next.js 15 this intentionally makes the route tree dynamically rendered, so server output, <html lang>, and hydrated components share the same locale.

Bearer auth

Runtime REST, GraphQL, MCP, and many automation flows use bearer tokens:

Authorization: Bearer <token>

Never place tokens in docs, page bundles, screenshots, or agent prompts. Use environment variables or client-specific secret storage.

Custom Page sign-out

Authenticated Custom Pages use the host-provided useSession() SDK action. Physical Operate and standalone sessions are supported; Agent Page Session, public-share, preview, Evaluation, and unauthenticated surfaces are explicitly unsupported and do not send a sign-out request.

On supported surfaces, the host validates same-origin app/surface context, signs out the physical identity session, clears selected-tenant, impersonation, and stale Agent Page Session cookies, and redirects only to /auth/login. The request contains no caller-supplied principal, tenant, impersonation, or redirect. Custom Page code must not call private auth routes or manage host cookies directly.

Design REST scripting tokens

Trusted Design MCP callers with full design scope can use mint_design_rest_token to create a temporary bearer token for local scripts that call documented Design REST endpoints. These tokens inherit the issuing principal and are scoped to the tenant, optional app, Design scope, and expiration.

Design REST scripting tokens are intentionally separate from runtime tokens: they are rejected by Runtime REST, Runtime GraphQL, and Runtime MCP surfaces. Use them only for short-lived Design automation and discard them after the script finishes.

OAuth for Design MCP

Human MCP clients should use OAuth when available. The app-scoped Design MCP endpoints support OAuth discovery and consent:

• read-only endpoint: design:read
• full design endpoint: design

Use Connect Design MCP for Claude, Codex, ChatGPT, and compatible MCP client setup.

OAuth access tokens expire after one hour. Compatible clients refresh them without another browser login and must persist the newly rotated refresh token after every successful refresh. A refresh request may omit scope, repeat the granted scope, or request a narrower scope that still satisfies the MCP resource. It cannot add permissions or change the resource. Concurrent refresh losers receive a retryable response without revoking the winning grant. If a successful response is lost before persistence, only the immediately previous credential is accepted, for one minute, and it is rotated again. Replay after that window remains an invalid_grant failure.

Common scopes

Scopes are necessary but not sufficient. The user or service must also have tenant and app access.

Actor context

Runtime calls should resolve an actor. The actor is used for permission checks, audit trails, command metadata, Activity, and agent-visible context.

For service integrations, use a service identity with only the required scopes. For human builders, prefer OAuth so consent and tenant/app selection are explicit.

Webhook auth

Inbound webhooks should verify signatures or shared secrets before mapping payloads into commands. A webhook that cannot be authenticated should not trigger business behavior.

Agent bridge tokens

Runtime agents can use service tokens scoped to the app and intended tool surface. Do not reuse Design MCP credentials for runtime-only agents.