Api keys

API keys authenticate requests to the Public API. Keys can be scoped to organizations, projects, or users with optional budget limits and expiration.

Create an API key

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Request Body

application/json

allowed_models?|null

Allowed models (null = all models)

budget_limit_cents?integer|null

Budget limit in cents

Formatint64

budget_period?null|BudgetPeriod

expires_at?string|null

Formatdate-time

ip_allowlist?|null

IP allowlist in CIDR notation (null = all IPs)

name*string

owner*||||

Owner of an API key

rate_limit_rpm?integer|null

Requests per minute override

Formatint32

rate_limit_tpm?integer|null

Tokens per minute override

Formatint32

scopes?|null

Permission scopes (null = full access)

Response Body

`application/json`

curl -X POST "https://loading/admin/v1/api-keys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "owner": {
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "organization"
    }
  }'

curl -X POST "https://loading/admin/v1/api-keys" \  -H "Content-Type: application/json" \  -d '{    "name": "Production API Key",    "owner": {      "org_id": "550e8400-e29b-41d4-a716-446655440000",      "type": "organization"    }  }'

{
  "api_key": {
    "budget_limit": null,
    "budget_period": null,
    "created_at": "2025-01-15T10:30:00Z",
    "expires_at": null,
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "key_prefix": "gw_live_abc",
    "name": "Production API Key",
    "owner": {
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "organization"
    },
    "revoked_at": null
  },
  "key": "gw_live_abc123def456ghi789jkl012mno345pqr678"
}

{
  "error": {
    "code": "not_found",
    "message": "Organization '550e8400-e29b-41d4-a716-446655440000' not found"
  }
}

Revoke an API key

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

key_id*string

API key ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://loading/admin/v1/api-keys/497f6eca-6276-4993-bfeb-53cbbbba6f08"

curl -X DELETE "https://loading/admin/v1/api-keys/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Rotate an API key

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

key_id*string

API key ID to rotate

Formatuuid

Request Body

application/json

grace_period_seconds?integer|null

Grace period in seconds during which both old and new keys are valid. Default: 86400 (24 hours). Maximum: 604800 (7 days).

Formatint64

Range0 <= value

Response Body

`application/json`

curl -X POST "https://loading/admin/v1/api-keys/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate" \
  -H "Content-Type: application/json" \
  -d '{
    "grace_period_seconds": 3600
  }'

curl -X POST "https://loading/admin/v1/api-keys/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate" \  -H "Content-Type: application/json" \  -d '{    "grace_period_seconds": 3600  }'

{
  "api_key": {
    "created_at": "2025-01-15T10:30:00Z",
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "key_prefix": "gw_live_xyz",
    "name": "Production API Key (rotated)",
    "owner": {
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "organization"
    },
    "rotated_from_key_id": "550e8400-e29b-41d4-a716-446655440001"
  },
  "key": "gw_live_xyz123abc456def789ghi012jkl345mno678"
}

{
  "error": {
    "code": "validation_error",
    "message": "Grace period cannot exceed 604800 seconds (7 days)"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "API key not found"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "API key is already being rotated"
  }
}

List API keys by organization

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

org_slug*string

Organization slug

Query Parameters

limit?integer|null

Maximum number of results to return

Formatint64

cursor?string|null

Cursor for keyset pagination. Encoded as base64 string.

direction?string|null

Pagination direction: "forward" (default) or "backward".

include_deleted?boolean|null

Include soft-deleted records in results

Response Body

`application/json`

curl -X GET "https://loading/admin/v1/organizations/string/api-keys"

curl -X GET "https://loading/admin/v1/organizations/string/api-keys"

{
  "data": [
    {
      "allowed_models": [
        "string"
      ],
      "budget_limit_cents": 0,
      "budget_period": {},
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip_allowlist": [
        "string"
      ],
      "key_prefix": "string",
      "last_used_at": "2019-08-24T14:15:22Z",
      "name": "string",
      "owner": {
        "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
        "type": "organization"
      },
      "rate_limit_rpm": 0,
      "rate_limit_tpm": 0,
      "revoked_at": "2019-08-24T14:15:22Z",
      "rotated_from_key_id": "4020a89e-8741-4a95-bbec-f0b312e899f2",
      "rotation_grace_until": "2019-08-24T14:15:22Z",
      "scopes": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 100,
    "next_cursor": "MTczMzU4MDgwMDAwMDphYmMxMjM0NS02Nzg5LTAxMjMtNDU2Ny0wMTIzNDU2Nzg5YWI",
    "prev_cursor": "string"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

List API keys by project

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

org_slug*string

Organization slug

project_slug*string

Project slug

Query Parameters

limit?integer|null

Maximum number of results to return

Formatint64

cursor?string|null

Cursor for keyset pagination. Encoded as base64 string.

direction?string|null

Pagination direction: "forward" (default) or "backward".

include_deleted?boolean|null

Include soft-deleted records in results

Response Body

`application/json`

curl -X GET "https://loading/admin/v1/organizations/string/projects/string/api-keys"

curl -X GET "https://loading/admin/v1/organizations/string/projects/string/api-keys"

{
  "data": [
    {
      "allowed_models": [
        "string"
      ],
      "budget_limit_cents": 0,
      "budget_period": {},
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip_allowlist": [
        "string"
      ],
      "key_prefix": "string",
      "last_used_at": "2019-08-24T14:15:22Z",
      "name": "string",
      "owner": {
        "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
        "type": "organization"
      },
      "rate_limit_rpm": 0,
      "rate_limit_tpm": 0,
      "revoked_at": "2019-08-24T14:15:22Z",
      "rotated_from_key_id": "4020a89e-8741-4a95-bbec-f0b312e899f2",
      "rotation_grace_until": "2019-08-24T14:15:22Z",
      "scopes": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 100,
    "next_cursor": "MTczMzU4MDgwMDAwMDphYmMxMjM0NS02Nzg5LTAxMjMtNDU2Ny0wMTIzNDU2Nzg5YWI",
    "prev_cursor": "string"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

List API keys by service account

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

org_slug*string

Organization slug

sa_slug*string

Service account slug

Query Parameters

limit?integer|null

Maximum number of results to return

Formatint64

cursor?string|null

Cursor for keyset pagination. Encoded as base64 string.

direction?string|null

Pagination direction: "forward" (default) or "backward".

include_deleted?boolean|null

Include soft-deleted records in results

Response Body

`application/json`

curl -X GET "https://loading/admin/v1/organizations/string/service-accounts/string/api-keys"

curl -X GET "https://loading/admin/v1/organizations/string/service-accounts/string/api-keys"

{
  "data": [
    {
      "allowed_models": [
        "string"
      ],
      "budget_limit_cents": 0,
      "budget_period": {},
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip_allowlist": [
        "string"
      ],
      "key_prefix": "string",
      "last_used_at": "2019-08-24T14:15:22Z",
      "name": "string",
      "owner": {
        "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
        "type": "organization"
      },
      "rate_limit_rpm": 0,
      "rate_limit_tpm": 0,
      "revoked_at": "2019-08-24T14:15:22Z",
      "rotated_from_key_id": "4020a89e-8741-4a95-bbec-f0b312e899f2",
      "rotation_grace_until": "2019-08-24T14:15:22Z",
      "scopes": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 100,
    "next_cursor": "MTczMzU4MDgwMDAwMDphYmMxMjM0NS02Nzg5LTAxMjMtNDU2Ny0wMTIzNDU2Nzg5YWI",
    "prev_cursor": "string"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

List API keys by user

Authorization

api_key

AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

user_id*string

User ID

Formatuuid

Query Parameters

limit?integer|null

Maximum number of results to return

Formatint64

cursor?string|null

Cursor for keyset pagination. Encoded as base64 string.

direction?string|null

Pagination direction: "forward" (default) or "backward".

include_deleted?boolean|null

Include soft-deleted records in results

Response Body

`application/json`

curl -X GET "https://loading/admin/v1/users/497f6eca-6276-4993-bfeb-53cbbbba6f08/api-keys"

curl -X GET "https://loading/admin/v1/users/497f6eca-6276-4993-bfeb-53cbbbba6f08/api-keys"

{
  "data": [
    {
      "allowed_models": [
        "string"
      ],
      "budget_limit_cents": 0,
      "budget_period": {},
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip_allowlist": [
        "string"
      ],
      "key_prefix": "string",
      "last_used_at": "2019-08-24T14:15:22Z",
      "name": "string",
      "owner": {
        "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
        "type": "organization"
      },
      "rate_limit_rpm": 0,
      "rate_limit_tpm": 0,
      "revoked_at": "2019-08-24T14:15:22Z",
      "rotated_from_key_id": "4020a89e-8741-4a95-bbec-f0b312e899f2",
      "rotation_grace_until": "2019-08-24T14:15:22Z",
      "scopes": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 100,
    "next_cursor": "MTczMzU4MDgwMDAwMDphYmMxMjM0NS02Nzg5LTAxMjMtNDU2Ny0wMTIzNDU2Nzg5YWI",
    "prev_cursor": "string"
  }
}

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

201application/json

404application/json

200

404application/json

201application/json

400application/json

404application/json

409application/json

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

200application/json

400application/json

403application/json

404application/json

200application/json

400application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`