Skip to content

Create a new hash-based API key

POST /api/v1/api-keys

POST /maas/api/v1/api-keys

Creates a new OpenAI-compatible API key (sk-oai-* format). Supports both permanent keys (no expiration) and expiring keys (with expiresIn parameter). The plaintext key is shown ONLY ONCE at creation time and cannot be retrieved again.

Authorization

Request body

Required.

Content type: application/json

Schema: object

Property Type Required Description
data object Yes
data.name string Yes

Human-readable name for the API key
data.description string No

Optional description
data.expiresIn string No

Optional expiration duration (e.g., "30d", "90d", "1h"). Omit for permanent key.
data.subscription string Yes

Subscription ID header to scope this API key to a specific subscription.
data.ephemeral boolean No

When true, requests an ephemeral key (short-lived); forwarded to maas-api.

Example:

{
  "data": {
    "name": "my-permanent-key",
    "description": "Production API key",
    "subscription": "premium-team-sub"
  }
}

Responses

Status Description Response body
201 Created

Created response.

object

application/json
400 Bad Request

Bad Request response.

 None
401 Unauthorized

Unauthorized response.

 None
500 Internal Server Error

Internal Server Error

 None

201 Created response body

Property Type Required Description
data object Yes
data.key string No

Plaintext API key (SHOWN ONCE, NEVER AGAIN)
data.keyPrefix string No

Display prefix for UI (e.g., sk-oai-abc)
data.id string No

Unique identifier for the key
data.name string No

Name of the key
data.createdAt string (date-time) No

Creation timestamp (RFC3339)
data.expiresAt string (date-time) No

Expiration timestamp (RFC3339), omitted for permanent keys

Example request

curl -X POST "/maas/api/v1/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": "my-permanent-key",
    "description": "Production API key",
    "subscription": "premium-team-sub"
  }
}'

Example response

201 Created, application/json

{
  "data": {
    "key": "string",
    "keyPrefix": "string",
    "id": "string",
    "name": "string",
    "createdAt": "2024-01-31T09:30:00Z",
    "expiresAt": "2024-01-31T09:30:00Z"
  }
}