> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and scopes

> Distinguish browser sessions, management keys, inference keys, principals, roles, and tenancy scopes.

`airmux` has separate credentials for management and inference. They are not interchangeable.

| Credential          | Prefix or transport | Purpose                                              |
| ------------------- | ------------------- | ---------------------------------------------------- |
| Browser session     | Secure cookie       | Webapp and browser-only management flows             |
| Management key      | `sk-cp-`            | Permission-limited `/api/v1` automation              |
| Inference key       | `sk-inf-`           | Model requests and model discovery for one workspace |
| Provider credential | Provider-specific   | Upstream authentication selected by the gateway      |

## Tenancy scopes

Management authority can be scoped to the instance, an organization, or one workspace. A scope covers only itself and its descendants:

* Instance scope can act across the installation
* Organization scope can act within one organization and its workspaces
* Workspace scope can act only within one workspace

Organizations and workspaces can be addressed by ID or slug in management URLs. Inference keys carry an immutable
organization and workspace identity in the bundle.

## Human and service principals

Human accounts sign in with a session and can approve the CLI device flow. Service accounts represent automation and
cannot use browser-only flows. Both can receive roles and management keys.

Roles grant permission sets at a scope:

| Scope        | Roles                                    |
| ------------ | ---------------------------------------- |
| Instance     | `owner`, `auditor`, `data_plane`         |
| Organization | `owner`, `admin`, `member`, `data_plane` |
| Workspace    | `admin`, `member`, `viewer`              |

The effective permission is the intersection of the principal's authority, the management key's permission ceiling, and
the target scope. A management key cannot delegate authority its caller or key principal does not have.

## Create a management key

```bash theme={null}
airmux management-keys create \
  --org "$ORG_ID" \
  --workspace production \
  --label deployment-automation \
  --permission workspaces.read \
  --permission inference-keys.manage
```

The token is shown once. Revoking a management key also revokes keys delegated from it.

## Inference keys

```bash theme={null}
airmux inference-keys create checkout-service --workspace production
```

Every inference key has an explicit, immutable owner whose identity is carried into policy evaluation. A caller can create a
self-owned key. A caller with both inference-key and membership management authority can instead select an
organization-managed service account in the same organization:

```bash theme={null}
airmux inference-keys create checkout-service \
  --workspace production \
  --owner "$CHECKOUT_SERVICE_ACCOUNT_ID"
```

Human users cannot create keys owned by another human, including when the creator is an administrator. The audit log records
the actual creator separately from the selected owner. Use organization-managed service accounts as the owners of application
and production credentials. Changing an owner requires minting a replacement key, rotating the application, and revoking the
old key.

An inference key authenticates one workspace's model requests and model discovery and is the unit targeted by selected-key
policies. Revocation becomes effective after the gateway adopts a bundle that no longer contains its hash. Removing workspace
membership revokes the owner's inference keys and playground sessions in that workspace; removing organization membership
does so throughout the organization. Re-adding membership never reactivates an old credential.

Send the key through `Authorization: Bearer` or `x-api-key`. See the [inference API overview](/docs/reference/inference)
for credential precedence and playground-cookie requirements.

See the [management API](/docs/reference/management-api) for bearer authentication and the
[CLI reference](/docs/reference/cli) for context management.

For account creation, invitations, roles, and public signup, see [Manage users and access](/docs/guides/user-management).