API Keys

API keys authenticate requests to the CastBrick API. Each key carries a permission scope that limits what it can do. You can create multiple keys for different environments or third-party integrations.

API key management endpoints require session authentication (JWT from logging in to the dashboard). They cannot be called with another API key.

Scopes

Scope	Access
`Sms`	Send and manage SMS only
`Full`	Full access to all API resources
`Playground`	Sandbox/test environment only

Create an API key

POST /keys

Request body

{
  "name": "Production server",
  "permission": "Sms"
}

Field	Type	Required	Description
`name`	`string`	No	Human-readable label for the key
`permission`	`string`	No	`Sms`, `Full`, or `Playground` (default: `Full`)

Response `201`

Returns the raw API key string. This is the only time the full key is shown — store it securely.

cb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Code sample

curl -X POST https://api.castbrick.co/v1/keys \
  -H "Authorization: Bearer <your_session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production server",
    "permission": "Sms"
  }'

List API keys

GET /keys

Returns your existing API keys. The key value itself is masked — only the prefix is shown.

Query parameters

Parameter	Default	Description
`pageNumber`	`1`	Page number
`pageSize`	`10`	Results per page

Response `200`

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Production server",
      "prefix": "cb_live_xxxx",
      "permission": "Sms",
      "createdAt": "2026-01-15T10:00:00Z",
      "lastUsedAt": "2026-05-07T09:12:00Z"
    }
  ],
  "totalCount": 2,
  "pageNumber": 1,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false
}

Code sample

curl https://api.castbrick.co/v1/keys \
  -H "Authorization: Bearer <your_session_jwt>"

Revoke an API key

DELETE /keys/{keyId}

Immediately invalidates the key. Any requests using it will receive 401 Unauthorized. This action is irreversible.

curl -X DELETE https://api.castbrick.co/v1/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <your_session_jwt>"

Returns 204 No Content.

Best practices

One key per service — create separate keys for your backend, CI pipelines, and third-party integrations
Use minimal scope — use Sms instead of Full when you only need to send messages
Rotate regularly — revoke and recreate keys every 90 days or after a security incident
Never commit keys — use environment variables: CASTBRICK_API_KEY=cb_live_...
Playground keys — use Playground scope during development to avoid sending real messages

# .env (never commit this file)
CASTBRICK_API_KEY=cb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Keys

On this page