> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Authentication

> Authenticate Cessy Runtime APIs, Design MCP, Runtime MCP, webhooks, subscriptions, adapters, and agent bridge calls.

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:

```http
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](/start/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

| Scope         | Meaning                                                             |
| ------------- | ------------------------------------------------------------------- |
| `openid`      | OpenID Connect identity scope used by OAuth clients.                |
| `read`        | Runtime read access.                                                |
| `write`       | Runtime write access.                                               |
| `runtime`     | Runtime API and Runtime MCP access for a tenant/app.                |
| `design:read` | Read-only Design MCP access for app model and reference inspection. |
| `design`      | Full Design MCP access for trusted builder automation.              |
| `admin`       | Administrative tenant and platform operations.                      |

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.