Admin API reference

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

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:

{
  "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:

{
  "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 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.

Get Started

Concepts

Connect

Guides

Reference

Admin API reference

Authentication

Endpoints

Databases (tenants)

Users

Service accounts

Credentials (tokens)

Capabilities

Health and metrics

Compatibility

​Authentication

​Endpoints

​Databases (tenants)

​Users

​Service accounts

​Credentials (tokens)

​Capabilities

​Health and metrics

​Compatibility

Authentication

Endpoints

Databases (tenants)

Users

Service accounts

Credentials (tokens)

Capabilities

Health and metrics

Compatibility