Authentication & Access

Who you are

The platform reads identity from the AI Gateway session. The auth.me action returns the current user, their workspaces, and role. The app's user menu and workspace switcher are built on it.

  • AI tool: auth_me
  • API: GET /api/invoke/auth.me

Workspace scoping

Every authenticated request resolves a user context and an active workspace. Action handlers narrow their reads and writes to that workspace, so:

  • Members can do everything within their workspace.
  • No request can reach data in a workspace you don't belong to.

Switching workspace (via the switcher in the top bar) changes which workspace subsequent actions scope to.

Roles

Actions may declare requiresRole. The dispatcher checks it before running the handler, so an unauthorized call is rejected up front. Roles include owner, admin, billing, member, developer, and viewer. As a rule, mutating actions deny the read-only viewer role. Most actions have no role gate at all — being a workspace member is enough.

Custom RBAC roles can be defined too; see the Roles reference.

Programmatic access (API keys)

For calling the platform from your own code or another agent, mint an API key. Keys are scoped to a workspace and carry a role, so the same role gates apply.

  • AI tools: api_keys_list, api_keys_create, api_keys_revoke
  • API: POST /api/invoke/api_keys.create

Send the key as a bearer token when calling /api/invoke/*. See Using the API for the request shape, and the API Keys reference for exact fields.

Secrets (the Vault)

Credentials the platform needs (integration tokens, signing secrets) live encrypted in the Vault. They're decrypted only into outbound requests and never returned to the client. See the Vault reference.