API Keys Management

Complete API reference for managing API keys. API keys provide programmatic access to customer-facing ScaleBox APIs.

Authentication Required: API key management APIs require an authenticated request. You can authenticate with X-API-Key, Authorization: Api-Key ..., or a supported bearer token.

Secret handling: the full api_key secret is returned only in the create (POST) response. Store it immediately. List, get, update, and status responses expose the display prefix only—the full secret is not stored server-side and cannot be retrieved later.

Standard Response Format

API key endpoints use the standard API envelope:

{
  "success": true,
  "data": {},
  "timestamp": "2026-04-17T12:34:56Z"
}

Delete uses a message-only success response.

API Endpoints

Create API Key

POST /v1/api-keys

Request body

Name	Type	Required	Description
name	string	Yes	API key name
description	string	No	Human-readable purpose

Response

{
  "success": true,
  "data": {
    "key_id": "key-abc123def456789",
    "name": "development-key",
    "description": "API key for local development",
    "api_key": "sk-1234567890abcdef1234567890abcdef12345678",
    "prefix": "sk-1234",
    "is_active": true,
    "created_at": "2026-04-17T12:00:00Z",
    "max_active_api_keys": 5,
    "owner": {
      "user_id": "usr-xyz789abc123456",
      "username": "developer",
      "display_name": "John Developer",
      "email": "john@example.com"
    }
  },
  "timestamp": "2026-04-17T12:00:00Z"
}

List API Keys

GET /v1/api-keys

Query parameters

Name	Type	Required	Description
user_id	string	No	Root users only: filter by owner user id
status	string	No	`active` or `inactive`
search	string	No	Name substring filter
sort_by	string	No	Sort column
sort_order	string	No	`asc` or `desc`
page	integer	No	Page number, default `1`
limit	integer	No	Page size (alias: `page_size`)
offset	integer	No	Offset (alias: `skip`)

Response

{
  "success": true,
  "data": {
    "api_keys": [
      {
        "key_id": "key-abc123def456789",
        "name": "development-key",
        "description": "API key for local development",
        "prefix": "sk-1234567",
        "is_active": true,
        "last_used_at": "2026-04-17T11:45:00Z",
        "created_at": "2026-04-10T10:00:00Z",
        "updated_at": "2026-04-17T11:45:00Z",
        "owner": {
          "user_id": "usr-xyz789abc123456",
          "username": "developer",
          "display_name": "John Developer",
          "email": "john@example.com"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    },
    "max_active_api_keys": 5
  },
  "timestamp": "2026-04-17T12:00:00Z"
}

Get API Key

GET /v1/api-keys/{key_id}

Returns metadata for one key. The full secret is not included.

Response

{
  "success": true,
  "data": {
    "key_id": "key-abc123def456789",
    "name": "development-key",
    "description": "API key for local development",
    "prefix": "sk-1234567",
    "is_active": true,
    "last_used_at": "2026-04-17T11:45:00Z",
    "created_at": "2026-04-10T10:00:00Z",
    "updated_at": "2026-04-17T11:45:00Z",
    "owner": {
      "user_id": "usr-xyz789abc123456",
      "username": "developer",
      "display_name": "John Developer",
      "email": "john@example.com"
    }
  },
  "timestamp": "2026-04-17T12:00:00Z"
}

Update API Key

PUT /v1/api-keys/{key_id}

Request body

Name	Type	Required	Description
name	string	No	New key name
description	string	No	New description

Response

{
  "success": true,
  "data": {
    "key_id": "key-abc123def456789",
    "name": "production-key",
    "description": "Updated API key for production use",
    "prefix": "sk-1234567",
    "is_active": true,
    "last_used_at": "2026-04-17T11:45:00Z",
    "created_at": "2026-04-10T10:00:00Z",
    "updated_at": "2026-04-17T12:05:00Z"
  },
  "timestamp": "2026-04-17T12:05:00Z"
}

Update API Key Status

PUT /v1/api-keys/{key_id}/status

Request body

Name	Type	Required	Description
is_active	boolean	Yes	`true` to enable, `false` to disable

Response

{
  "success": true,
  "data": {
    "message": "API key disabled successfully",
    "is_active": false
  },
  "timestamp": "2026-04-17T12:06:00Z"
}

Delete API Key

DELETE /v1/api-keys/{key_id}

Response

{
  "success": true,
  "message": "API key deleted successfully",
  "timestamp": "2026-04-17T12:07:00Z"
}

Validation Notes

API key names use strict validation rules from the backend.
Duplicate names return 409 Conflict.
Each user can have up to five active API keys by default. Disabled keys do not count toward the limit.
List and create responses include max_active_api_keys with the effective limit for the authenticated user.
If you lose a key secret, delete the old key and create a new one; ScaleBox cannot show the full secret again.
The create response uses a shorter prefix than list/get/update. The examples above reflect the actual backend behavior.

Common Errors

{
  "success": false,
  "error": "An API key with this name already exists for your account",
  "timestamp": "2026-04-17T12:10:00Z"
}

Common API key errors:

400: invalid request body, invalid key name, or key-count limit reached
401: invalid or missing auth
404: key not found in your accessible scope
409: duplicate key name
500: database or key-generation failure

API Keys Management

On this page