Govern

An API client is a project-scoped machine identity for a non-human workload: a worker, CI job, server, or other process that authenticates with an API key.

Machine identity is the broader implementation model. It is the durable "who" behind API clients, agents, and system-owned work.

Mobius separates three concepts:

API keys and CLI credentials are credentials. Roles attach to principals. Audit logs record both the principal and the credential.

Kinds

Human principals exist too, but they are managed through organization membership and Clerk-backed login rather than the machine identity surface.

Create an API client

An API client is the user-facing name for a standalone service principal. Create one when a workload needs its own permissions and keys. Open Settings > Access, click New API client, then choose its roles and create the first key.

Rotate by creating a second key, moving the workload, confirming last_used_at, then revoking the old key.

Agents are principals

Every agent has an immutable principal_id. Role assignments and audit logs use that principal. Agent-owned tables, artifacts, and run actions use it too.

Do not create a separate API client for an agent unless a separate external process needs to authenticate as its own workload. The agent's own role grants should live on the agent principal.

Access in the app

Project Access has two complementary sections:

• Members: human users in the organization and their project roles.
• Machine identities: API clients plus machine principals that agents and Mobius provision automatically.

Open a machine identity to assign roles, disable it, inspect keys, or create a new key.

Use the CLI command reference for terminal management and the Access-control API for application code.

Good boundaries

• Use one API client per workload, not one global key for everything.
• Assign narrow roles to API clients. Reserve broad admin roles for humans.
• Disable a principal when the whole workload should stop authenticating.
• Revoke a key when only that credential should stop working.
• Use principal_id to audit "who acted" and credential_id to audit "which token or CLI device did it."

Next

• API keys are credentials for machine principals.
• Create an API key walks the app and CLI flows.
• Roles explains assignments and permissions.
• Agents are machine principals with AI configuration.
• Audit logs show principal plus credential attribution.