> ## 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.

# Management API overview

> Authenticate to the control plane, address tenant scopes, unwrap envelopes, handle errors, and browse generated endpoints.

The control plane is served at `/api/v1`. The generated endpoint pages in this reference come directly from `lib/api-spec/openapi.yaml`.

## Authentication

Automation sends a management key:

```text theme={null}
Authorization: Bearer sk-cp-your-key
```

Browser sessions use the `airmux_session` cookie and must also send `X-Requested-With`. Inference keys are not accepted by management endpoints.

## Scope in URLs

| Scope        | Path pattern                                                    |
| ------------ | --------------------------------------------------------------- |
| Instance     | `/api/v1/instance/...` or another instance resource             |
| Organization | `/api/v1/organizations/{org_id}/...`                            |
| Workspace    | `/api/v1/organizations/{org_id}/workspaces/{workspace_ref}/...` |

`org_id` and `workspace_ref` accept the resource UUID or slug where the endpoint documents that behavior. A scoped
management key must cover the target, and its permission ceiling must include the operation.

## Response envelope

Every successful management response wraps its result once:

```json theme={null}
{
  "data": {
    "id": "019...",
    "name": "Production",
    "slug": "production"
  }
}
```

Growing collections add page metadata:

```json theme={null}
{
  "data": [{ "id": "019...", "name": "Production" }],
  "page": { "next_cursor": "MDE5Li4u" }
}
```

Configuration, status, and selection endpoints return the complete set as `{"data": [...]}`. This includes management
keys, provider credentials, data-plane status, invitations, enrollment choices, and candidate pickers. Errors retain
FastAPI's `{"detail": ...}` shape and are not enveloped.

## Example

```bash theme={null}
curl https://llm.example.com/api/v1/organizations/$ORG_ID/workspaces \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY" \
  -H 'Accept: application/json'
```

## Permissions

Permission names are closed strings grouped by resource:

* `organizations.read|create|update|delete`
* `principals.read|manage`
* `members.read|manage`
* `workspaces.read|create|update|delete`
* `catalog.read|manage`
* `provider-credentials.read|manage`
* `inference-keys.read|manage`
* `policies.read|manage`
* `playground.execute`
* `bundles.read`
* `usage.read|ingest`
* `data-planes.read|heartbeat`
* `audit.read`
* `management-keys.read|issue|revoke`

## One-time secrets

Inference-key creation, management-key creation, invitation issue/reissue, and service-account creation actions can return
a one-time secret. Store the returned value immediately; later list and get operations return metadata only.

## Pagination

Collections that callers browse incrementally use cursor pagination. Pagination is not added to an endpoint merely
because it is scoped or returns a list; consumers of configuration and selection endpoints need the complete set.

The paginated collections are organizations, usage events, and audit activity. Usage events are paginated
at both organization and workspace scope, and audit activity is paginated at instance and organization scope.

* `limit` is the maximum number of results per page, defaults to 50, and accepts 1 through 200
* `cursor` is the opaque `page.next_cursor` returned by the preceding request
* `page.next_cursor` is `null` when no later page exists

Do not decode or edit a cursor. Invalid and oversized cursors return `422` with `{"detail":"invalid cursor"}`. Cursors
identify a sort position, so traversal can continue if the item at the previous page boundary is deleted.

```bash theme={null}
curl 'https://llm.example.com/api/v1/organizations?limit=50' \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY"

curl "https://llm.example.com/api/v1/organizations?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY"
```

Use the endpoint pages that follow this overview for request bodies, response schemas, required permissions, and interactive examples.