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

# Admin API

> Manage your AI Reserve organization from code: members, teams, budgets, keys, settings, routing, GPUs, containers and training over plain HTTP, the SDKs or the CLI.

Everything an enterprise admin does in the portal — and everything a member does for
themselves — is an **operation**. The admin API exposes every operation three ways, from one
definition, with one credential and one result shape:

| Door | Spelling |
| - | - |
| HTTP | `POST https://api.aireserve.com/v1/admin/{opId}`, input as the JSON body |
| SDKs | `client.admin.<domain>.<operation>(input)` (TypeScript), `admin.<Domain>.<Operation>` (Go) |
| CLI | `aireserve admin <domain> <operation> --flag …` |
| [MCP server](https://docs.aireserve.com/connect/mcp.md) | a tool named `{opId}` for your coding agent |

The full list — 137 operations across 12 domains, with who may call each — is the
[operation reference](https://docs.aireserve.com/connect/mcp-tools.md). The OpenAPI document under **API reference** lists
every `/v1/admin/*` path with its request schema.

## Authentication

The admin API takes a **management token** (`aireserve_mcp_…`), never an inference API key.
Get one by signing in:

```shell theme={"dark"}
curl -fsSL https://get.aireserve.com/install.sh | sh -s -- --no-configure
aireserve login            # opens the browser; the token lands in the CLI credential store
```

or by minting one on the portal [Keys page](https://portal.aireserve.com/keys?type=mcp) under
**Management Keys** (expiring, revocable, shown once), or by completing an MCP client's
Authenticate step. All three mint the same kind of token through the same OAuth-backed
lifecycle; `aireserve login` is the standard OAuth authorization-code + PKCE flow against the
portal, with a loopback redirect.

```shell theme={"dark"}
export AIRESERVE_MCP_TOKEN="aireserve_mcp_…"
```

A token is its owner. There are no scopes to choose: every call is authorized live from the
owner's current role, so a member's token can do what a member can do and an enterprise
admin's token can run the organization. Revoke it on the Keys page; revocation applies on the
next request. Inference keys are refused with `401 invalid_token`.

## Discover what you can call

```shell theme={"dark"}
curl https://api.aireserve.com/v1/admin/ops \
  -H "Authorization: Bearer $AIRESERVE_MCP_TOKEN"
```

```json theme={"dark"}
{
  "ops": [
    {
      "id": "invite_user",
      "domain": "members",
      "kind": "write",
      "blurb": "Invite a new member to the organization …",
      "alwaysConfirm": true,
      "secretReturning": false,
      "inputSchema": { "type": "object", "properties": { "email": { "type": "string" }, … }, "required": ["email"] }
    }
  ]
}
```

The catalog is filtered by your role, so a member sees the personal surface and an enterprise
admin sees the whole organization. `alwaysConfirm` marks operations an interactive client
should confirm with its user first (the MCP server enforces a confirm step; the HTTP door
does not — callers are code). `secretReturning` marks operations whose result carries a
one-time secret.

## Call an operation

```shell theme={"dark"}
curl https://api.aireserve.com/v1/admin/invite_user \
  -H "Authorization: Bearer $AIRESERVE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"jordan@acme.com","role":"member"}'
```

```json theme={"dark"}
{
  "status": "executed",
  "ok": true,
  "summary": "Invite jordan@acme.com as a member",
  "message": "Invitation sent to jordan@acme.com",
  "data": { "userId": "9cba8ede-…" }
}
```

Every operation returns the same envelope. `summary` is the consent line, built from the rows
the operation touched; `message` is the human result; `data` is the read payload or write
detail. Reads are the same call with their own body: `POST /v1/admin/list_org_users` with
`{}`.

| Status | Meaning |
| - | - |
| `200` | Executed, `ok: true` |
| `422` | Executed, but the operation reported a failure — read `message` |
| `400` | The body does not match the operation's schema (`invalid_input`) |
| `403` | The operation is not available at your role (`not_allowed`) |
| `404` | Unknown operation id (`unknown_op`) |
| `401` | Missing, expired or revoked token, or an inference key |
| `429` | Organization request budget exhausted; see `Retry-After` |

Refusals carry `{"status": "refused", "code": …, "error": …}`.

## Secrets

Operations that mint a credential — `create_api_key`, `create_client_api_key`,
`create_team_api_key`, `create_ecs_credential` — return it once:

```json theme={"dark"}
{
  "status": "executed",
  "ok": true,
  "summary": "Create organization API key \"CI pipeline\"",
  "message": "API key \"CI pipeline\" created (prefix aireserve_api_7f3…)",
  "data": { "keyId": "d0e1…" },
  "secret": "aireserve_api_7f3…",
  "sensitive": true
}
```

`sensitive: true` is present exactly when `secret` is. Store the value immediately and keep
the response out of logs; only its hash is kept on our side and it is never shown again.

## SDKs and CLI

The SDK admin modules and the `aireserve admin` commands are generated from the same OpenAPI
document as this page, so a new operation appears in all of them without hand work.

```typescript TypeScript theme={"dark"}
import { Aireserve } from "@aireserve/sdk";

const client = new Aireserve({ managementToken: process.env.AIRESERVE_MCP_TOKEN });
const users = await client.admin.members.listOrgUsers({});
const invited = await client.admin.members.inviteUser({ email: "jordan@acme.com", role: "member" });
```

```go Go theme={"dark"}
client := audacityadmin.New(audacityadmin.Options{ManagementToken: os.Getenv("AIRESERVE_MCP_TOKEN")})
users, err := client.Members.ListOrgUsers(ctx, map[string]any{})
```

```shell CLI theme={"dark"}
aireserve login
aireserve admin ops                                  # what your token may call
aireserve admin members list-org-users
aireserve admin members invite-user --email jordan@acme.com --role member
aireserve admin api-keys create-client-api-key --name "CI pipeline" --yes
```

High-stakes operations in the CLI (`alwaysConfirm`) ask for `--yes` or an interactive
confirmation; the SDKs run them directly.

## Limits of the surface

* **Portal-only operations.** Hard-deleting a user, purging the organization's stored
  content, and removing or reopening a sign-in domain are not on the admin API or the MCP
  server. They stay behind a browser click.
* **No platform operations.** Creating organizations, funding wallets, system users and other
  super-admin work is not exposed; a super admin's token acts as an enterprise admin of their
  own organization.
* **No impersonation, no file bytes.** Identity swaps and uploads stay in the portal.
* **Same guards as the portal.** Each operation ends in the server action the portal calls;
  its authorization, audit log and invariants run unchanged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.