Authentication | Cessy Builder Docs

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

Bearer auth

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

1 Authorization: Bearer <token>

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

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 ces setup.

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.