API keys

An API key is a long-lived bearer token your workers, CI jobs, and backend services use to talk to Mobius. Every key is:

• Project-scoped: one key authenticates inside one project.
• Bound to a machine principal: the principal is the durable identity; the key is only a credential.
• Shown once: create returns the raw key; later reads expose only the key_prefix.

Permissions do not live on the key. They live on the machine principal the key authenticates as. To change what a key can do, change the role assignments on that principal.

Why principals

Treat machine principals the way you treat IAM principals: durable identities with permission sets. Rotate the key and the principal keeps its permissions. Change the principal's roles and every key for that principal picks up the new access without re-issue.

This is why most "I need a new key" requests should really be "I need the right API client." Reuse the existing API client when it represents the same workload; mint a new key for rotation or deployment.

Picking the right API client

For workloads, default to one of the system roles or a small custom project role:

See Roles for presets and for how to inspect the current permission catalog.

Working with keys

Create an API client first if the workload does not already have one:

WORKER_ROLE_ID="$(mobius roles list -o json \
  | jq -r '.items[] | select(.name=="Worker") | .id')"
 
mobius principals create \
  --name worker-prod \
  --description "Production worker process" \
  --role-ids "$WORKER_ROLE_ID" \
  -o json

Then issue a key for that principal:

mobius api-keys create \
  --name worker-prod-primary \
  --principal-id prin_01... \
  --expires-at 2027-01-01T00:00:00Z

Inventory and revoke:

mobius api-keys list
mobius api-keys get key_01...
mobius api-keys revoke key_01...

The create command returns the raw key once. Store it in your secret manager immediately; there is no recovery path if you lose it.

Use the key by exporting it:

export MOBIUS_API_KEY="mbx_..."

The CLI and SDKs read this environment variable by default.

Hygiene

A few practices worth adopting from day one:

• One key per deployment path. "Worker prod primary", "Worker prod rotation", "CI deploy". Usage and rotation are easier when key names map to actual processes.
• One API client per workload. Reusing a principal across unrelated systems makes role changes hard to reason about.
• Set expires_at for short-lived tokens. Ephemeral CI or test keys should expire in days, not years.
• Watch last_used_at. If a key has not been used in months, revoke it.
• Do not share keys between humans. Humans should run mobius auth login and use their own browser-issued credential.

What a key cannot do

• It cannot grant itself permissions. Roles go through principal assignments.
• It cannot be retrieved after creation. The full token is only in the create response.
• It cannot span projects. Each project has its own principals and keys.

If one workload operates across projects, create a principal and key in each project, or use an interactive user credential where human attribution is required.

Related

• Create an API key walks the UI and CLI flows end to end.
• Machine identities explains principals, API clients, and agent identities.
• Roles is where permissions are managed.
• Workers use API keys to open the worker connection.
• Audit logs record credential_id and principal_id on mutations.