Create an API key

Creates a new project-scoped API key. The plaintext api_key is returned EXACTLY ONCE in the response; AVTR stores only the SHA-256 hash and cannot recover the plaintext.

V0 API keys do NOT expire (Decision D6). Only explicit revocation (DELETE /v1/api-keys/{key_id}) disables them.

POST/v1/api-keys

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <api_key>`

x-api-keyAPI key · headerrequired

`x-api-key: <api_key>`

Request body

requiredapplication/json

API key creation request.

namestringrequired

Human-readable key name (e.g. `prod-server`). 1..128 characters.

min length 1 · max length 128

scopesstring[]required

Requested scopes for the API key. Must be non-empty.

min items 1

Responses

200API key created. `api_key` is returned exactly once.

api_keystringrequired

Plaintext API key (e.g. `avtr_live_...`). Returned EXACTLY ONCE. AVTR stores only the SHA-256 hash; the plaintext cannot be recovered. The caller MUST store this value securely immediately.

min length 1

created_atintegerrequired

Unix epoch milliseconds when the key was created.

min 0

key_idstringrequired

API key identifier (server-issued, opaque).

min length 1 · matches ^avtr_key_[A-Za-z0-9_-]+$

namestringrequired

min length 1

scopesstring[]required

Requested scopes for the API key. Must be non-empty.

min items 1

400Invalid request body or unknown scope.

Any of:

object

codestringrequired

Allowed:AVTR_PROVIDER_DOWNSTREAM_FAILEDAVTR_PROVIDER_TIMEOUTAVTR_PROVIDER_UNAVAILABLEAVTR_RATE_LIMIT_CONCURRENT_SESSIONSAVTR_RATE_LIMIT_EXCEEDEDAVTR_RATE_LIMIT_PROVIDER_QUOTAAVTR_RENDER_CAPACITYAVTR_RENDER_TIMEOUTAVTR_SESSION_STATE_UNAVAILABLEAVTR_SFU_CONNECTION_FAILEDAVTR_SFU_NEGOTIATION_FAILEDAVTR_SFU_ROOM_FULL

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

Allowed:AVTR_AUTH_EXPIRED_TOKENAVTR_AUTH_FORBIDDENAVTR_AUTH_INVALID_KEYAVTR_AUTH_MISSING_CREDENTIALSAVTR_AUTH_MISSING_SCOPEAVTR_PROVIDER_MISCONFIGUREDAVTR_RENDER_FAILEDAVTR_RENDER_MISCONFIGUREDAVTR_SESSION_CANCELLEDAVTR_SESSION_CONFLICTAVTR_SESSION_ENDEDAVTR_SESSION_NOT_FOUNDAVTR_SFU_NOT_CONFIGURED

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

401API key missing or invalid.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

403Missing `api_keys:write` scope.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

429Rate limit exceeded.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

500Unexpected internal error during key creation.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

curl -X POST "https://api.avtr.internal/v1/v1/api-keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "scopes": [
    "sessions:read"
  ]
}'

const response = await fetch("https://api.avtr.internal/v1/v1/api-keys", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "string",
  "scopes": [
    "sessions:read"
  ]
})
});

import requests

response = requests.post(
    "https://api.avtr.internal/v1/v1/api-keys",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "name": "string",
  "scopes": [
    "sessions:read"
  ]
},
)

Response

{
  "api_key": "string",
  "created_at": 0,
  "key_id": "avtr_key_01HABCDEFGH",
  "name": "string",
  "scopes": [
    "sessions:read"
  ]
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}