mobius

Get started free
Get started free

Operations

Create a project API key

Project API keys authenticate as an API client. Create or pick the API client first, then mint a key for it.

This guide creates a project-scoped key. Use an organization-level key only when one workload has to administer multiple projects.

In the app

  1. Open Projects > [your project] > Access.

  2. In Machine identities, either click New API client or open the existing API client for this workload.

  3. If you create a client, enter a name, optional owner, and any initial roles. Roles control what every key for this client can do.

  4. On the API client detail page, open Keys and click Create key.

  5. Enter a key name like primary, ci-deploy, or local-dev-worker.

  6. Click Create key. Mobius shows the raw mbx_... token once.

  7. Copy it now, then store it in your secret manager or shell:

    export MOBIUS_API_KEY="mbx_..."

A key row with an empty last_used_at means the key exists but has not been used yet.

From the CLI

Migration note: Project API-key creation now rejects principals with no role assignments. Existing create-principal, create-key, then assign-role automation must assign the role before minting the key, use the compound command below, or explicitly pass --allow-unassigned-principal for a deliberately dormant credential.

Once you have a bootstrap credential, either from mobius auth login or from an existing admin key, create the API client, assign a role, and mint its first key in one command:

mobius principals create worker-prod \
  --description "Production worker process" \
  --role Worker \
  --with-key \
  --key-name worker-prod-primary \
  --expires-at 2027-01-01T00:00:00Z

Mobius prints the raw key once. Store it immediately. For separate lifecycle control, create the principal first:

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 mint a key for the returned principal ID:

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

The key command prints the new key once. By default the CLI pretty-prints on a TTY and emits JSON when piped, so this works as expected:

mobius api-keys create \
  --name worker-prod-primary \
  --principal-id prin_01... \
  -o json \
  | jq -r .key > ~/.config/mobius/worker-prod.key
chmod 600 ~/.config/mobius/worker-prod.key

There is no recovery path for a lost raw key. If you miss the create output, delete and reissue:

mobius api-keys list
mobius api-keys delete key_01...

Using the key

Every CLI and SDK call reads MOBIUS_API_KEY from the environment by default:

export MOBIUS_API_KEY="mbx_..."
mobius loops list

For HTTP calls, the bearer header is:

Authorization: Bearer mbx_...

Organization-level keys

Create organization-level keys from Organization > API Keys in the app or through POST /v1/api-keys. They are not tied to one project API client. They act as the organization's system principal with the role selected at creation time.

Prefer a project key for workers, CI tied to one project, and any process that can be scoped narrowly. Organization-level keys are for cross-project administration.

Troubleshooting

  • Create failed with principal_has_no_roles. Assign at least one project role first. If you intentionally need a dormant key, pass --allow-unassigned-principal; it cannot access project resources until you add a role.
  • Create failed. The key name is empty or already used inside the project, or the selected principal is disabled.
  • 401 immediately on first use. The API client may be disabled, the key may be expired or revoked, or the request may be pointed at the wrong project.
  • permission_denied on project calls. The response names the missing permission. Assign a role that grants it, such as Viewer, Worker, Operator, or a custom project role.
  • You closed the reveal without copying. Revoke the key row and create a new key.
  • Worker connects but cannot claim jobs. The principal needs mobius.work.execute. The worker preset includes it.
  • Org key fails on a worker or project-pinned model route. Use a project API key. Those surfaces require a project-scoped credential.