Guides

This guide creates an identity and API key for software that works in your Mobius organization. At the end, you will make one harmless request with the new key.

Use an API key for a backend, CI job, script, or self-hosted worker. Read Organizations and access for the identity, permission, and rotation model behind the steps below.

Before you start

• Install and sign in to the CLI if you will use the command-line flow.
• Have permission to manage access. Organization Owners and Admins have it, as does anyone holding a role with mobius.org.admin.
• Choose the narrowest built-in role that fits the software:

Replace the example names everywhere they appear.

Create the key in the app

1. Open Settings > Access.
2. Under Machine identities, click New API client.
3. Enter a permanent name for this software, such as worker-prod. The optional Owner records the accountable person; it does not grant access.
4. Review Roles. The form starts with Admin selected. Remove it unless this software must manage access, then choose the intended role.
5. Click Create API client.
6. Open the new API client. Under Keys, click Create key.
7. Enter a name such as primary and click Create key.
8. Copy the complete mbx_... value from the reveal alert into the software's secret manager. Mobius will not show it again.

Do not paste the key into source code, a ticket, chat, logs, or a screenshot. If you close the reveal before saving the full value, delete that key and create a new one.

Create the key from the CLI

The CLI calls API clients principals in its command names. The command below creates the same software identity as New API client in the app.

The compound command creates the API client, assigns its role, and creates its first key together:

mobius principals create worker-prod --role Worker --with-key --key-name worker-prod-primary --output json

This example is for a self-hosted worker. Replace Worker with the exact role you chose in the table above when you are creating a key for other software.

For a temporary key, pass the desired absolute expiry time to --expires-at in RFC 3339 format. Omit it when your organization manages expiry through its own rotation schedule.

Success includes both records. The full key appears only in this response:

{
  "principal": {
    "id": "prin_...",
    "name": "worker-prod"
  },
  "key": {
    "id": "key_...",
    "key": "mbx_..."
  }
}

Save the key.key value in the software's secret manager before closing the terminal. Avoid redirecting the creation command straight to a file: a failed pipeline can create the server-side key but lose its one-time value.

If the API client already exists, open it in the app and create another key, or find its principal ID from the CLI:

mobius principals list --fields id,name,state --output json

Copy the id for the intended client, then use it with:

mobius api-keys create --name replacement --principal-id prin_... --output json

Verify the key

For a deployment or CI job, set MOBIUS_API_KEY through its secret manager. For a local check, prompt for the value so the key itself is not saved in shell history. Bash and similar shells use:

IFS= read -rsp "Mobius API key: " MOBIUS_API_KEY && printf '\n'
export MOBIUS_API_KEY

PowerShell uses:

$secureKey = Read-Host "Mobius API key" -AsSecureString
$env:MOBIUS_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password

Now run a read with the new key. The explicit --api-key option prevents an existing login from hiding a mistake. Every built-in role in this guide can read organization data, so this check works for Viewer, Operator, Editor, Worker, and Admin keys:

mobius agents list --api-key "$MOBIUS_API_KEY" --fields id,name --output json

PowerShell uses $env:MOBIUS_API_KEY in place of $MOBIUS_API_KEY.

A JSON response, including an empty items list, proves that the key authenticated and can read the organization. It does not prove that the API client has only the intended permissions. Test one operation the software should be allowed to perform and one it should be denied, using non-production data.

The key row under Settings > Access > [API client] > Keys shows Last used after Mobius authenticates a request. The timestamp may update shortly after the request rather than immediately.

If it does not work

• principal_has_no_roles while creating a key: assign at least one role to the API client, then try again.
• 401: confirm the process received the complete mbx_... value and that the key is not expired or deleted and its API client is not disabled.
• permission_denied: the API client lacks the permission required by that operation. Review its roles instead of replacing the key.
• A self-hosted worker connects but cannot claim work: assign the Worker role and reconnect it.

To rotate a working credential, create a second key on the same API client, deploy and verify it everywhere, then delete the old key. If a key may have leaked, delete it immediately. Disable the API client when you need to stop all of its keys together.

See Organizations and access for the identity, permission, and rotation model.