Concepts

Machine identities

A machine identity is a non-human principal inside a project. It is the durable "who" behind API clients, agents, and system-owned work.

Mobius separates three concepts:

Concept	Question it answers
Principal	Who is acting?
Credential	How did the request authenticate?
Role assignment	What is the principal allowed to do?

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

Kinds

Kind	Created by	Common use
`service`	Project Access -> New API client, or `mobius principals create`	Workers, CI, servers, and other API clients.
`agent`	Agent creation	AI agents, sessions, and agent-owned resources.
`system`	Mobius provisioning	Internal platform work where a project-scoped machine principal is needed.

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

API clients

An API client is the user-facing name for a standalone service principal. Create one when a workload needs its own permissions and keys:

mobius principals create --name worker-prod

Then create one or more API keys for it:

mobius api-keys create \
  --name primary \
  --principal-id prin_01...

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. That principal is used for role assignments, ownership, audit attribution, table grants, artifact scope, and interaction responses.

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.

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."

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.