Mobius

Sign inGet started
GuidesAPI Reference
Sign inGet started

Guides

Create an API key

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

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

Once you have a bootstrap credential, either from mobius auth login or from an existing admin key, create an API client:

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 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, revoke and reissue:

mobius api-keys list
mobius api-keys revoke 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 automations list

For HTTP calls, the bearer header is:

Authorization: Bearer mbx_...

Troubleshooting

  • 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.
  • 403 on project calls. The principal exists but lacks the required role. Open the API client in Access and assign a preset 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.