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

# Admin API reference

> HTTP endpoints for managing Airhouse databases, users, service accounts, and short-lived credentials.

The Admin API is served on the Airhouse HTTP port (default `8080`) when the control plane is configured. All endpoints are under `/admin/v1/`, accept and return JSON, and require a bearer token in the `Authorization` header.

In the API, databases are called **tenants**. A tenant's `id` is the database name clients pass when they connect.

## Authentication

| Token | How you get it | Can call |
| - | - | - |
| Admin token | Set by the operator in the server configuration (`admin_token` / `AIRHOUSE_CP_ADMIN_TOKEN`) | Every endpoint except minting credentials |
| Service-account bearer | Returned once when a service account is created | Mint credentials for its database, revoke credentials it minted, and read capabilities |

```text theme={null}
Authorization: Bearer <token>
```

A missing or wrong token returns `401 Unauthorized`.

## Endpoints

### Databases (tenants)

| Method | Path | Body | Success | Notes |
| - | - | - | - | - |
| `POST` | `/admin/v1/tenants` | `{"id": "..."}` | `201` + tenant | `400` invalid id, `409` already exists |
| `GET` | `/admin/v1/tenants` | | `200` + tenant list | |
| `GET` | `/admin/v1/tenants/{id}` | | `200` + tenant | `404` if it doesn't exist |
| `DELETE` | `/admin/v1/tenants/{id}` | | `204` | Idempotent. Doesn't delete Parquet files in object storage. |

Tenant IDs may contain ASCII letters, digits, `_`, and `-`, up to 63 characters.

### Users

| Method | Path | Body | Success | Notes |
| - | - | - | - | - |
| `POST` | `/admin/v1/tenants/{id}/users` | `{"username", "password", "role"}` | `201` + user | `role` is `reader` (default), `writer`, or `admin`. Anything else returns `400`. |
| `GET` | `/admin/v1/tenants/{id}/users` | | `200` + user list | Excludes minted credentials |
| `DELETE` | `/admin/v1/tenants/{id}/users/{username}` | | `204` | `404` if the user doesn't exist |

User object:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "acme",
  "username": "alice",
  "role": "reader",
  "created_at": "2026-04-29T10:01:00Z"
}
```

### Service accounts

Require the admin token.

| Method | Path | Body | Success | Notes |
| - | - | - | - | - |
| `POST` | `/admin/v1/service-accounts` | `{"name", "tenant_id", "max_role", "max_ttl_secs"}` | `201` + service account, including `bearer` | The `bearer` is returned only here. `max_ttl_secs` is at most `86400`. |
| `GET` | `/admin/v1/service-accounts` | | `200` + list | Never includes bearers |
| `DELETE` | `/admin/v1/service-accounts/{id}` | | `204` | Idempotent. The bearer stops working immediately. |

### Credentials (tokens)

| Method | Path | Auth | Body | Success |
| - | - | - | - | - |
| `POST` | `/admin/v1/tenants/{id}/tokens` | Service-account bearer | `{"subject", "role", "ttl_secs", "write_schemas"?}` | `201` + credential |
| `DELETE` | `/admin/v1/tenants/{id}/tokens/{username}` | Admin token, or the service account that minted it | | `204` |

Credential object:

```json theme={null}
{
  "username": "eph_a1b2c3d4ef98",
  "password": "tk_...",
  "tenant": "acme",
  "role": "writer",
  "expires_at": "2026-05-05T12:15:00Z",
  "service_account_id": "sa_8f2a8c10",
  "write_schemas": ["app_store_ops"]
}
```

`write_schemas` is present only when you requested a scoped writer. See [Service accounts](../guides/service-accounts) for field rules and error codes.

### Capabilities

| Method | Path | Auth | Success |
| - | - | - | - |
| `GET` | `/admin/v1/capabilities` | Admin token or service-account bearer | `200` + `{"mint.write_schemas": true}` |

Servers that predate this endpoint return `404`.

## Health and metrics

These endpoints don't require authentication and are useful for load balancers and monitoring:

| Path | Purpose |
| - | - |
| `GET /healthz` | Liveness: the process is up |
| `GET /readyz` | Readiness: the server can accept traffic |
| `GET /metrics` | Prometheus metrics |

## Compatibility

Airhouse avoids breaking changes to existing `/admin/v1/` endpoints. New fields and endpoints may be added, so ignore response fields you don't recognize.


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