Create API key

POST https://app.speybooks.com/api/v1/api-keys/

Generate a new API key. The full plaintext key is returned exactly once in the response — it cannot be retrieved again. Store it securely immediately.

The key is hashed with Argon2id before storage. Default scopes grant full access (["*"]). Invalid scopes are rejected with a validation error listing the bad values.

Body parameters

environment string optional

Key environment. Live keys use sk_live_ prefix, test keys use sk_test_.

livetest

name string optional

Human-readable name for the key (e.g. Production Backend).

max length: 100

scopes array<string> optional

Permission scopes. Use ["*"] for full access, or specific scopes like ["invoices:read", "contacts"].

min items: 1 · max items: 20

Response

201 API key created. The full key is returned ONCE in this response and cannot be retrieved again.

Show response fields

createdAt string date-time

environment string

id integer

key string

keyPreview string

name string

scopes array<string>

scopesSummary string

warning string

Error codes

400 Validation error: invalid scope(s) or missing required fields.

Request POST /v1/api-keys/ curl

curl -X POST https://api.speybooks.com/v1/api-keys \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline", "environment": "live", "scopes": ["invoices", "contacts:read"]}'

Response 201

{
  "success": true,
  "data": {
    "id": 8,
    "key": "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "keyPreview": "sk_live_...o5p6",
    "name": "CI/CD Pipeline",
    "environment": "live",
    "scopes": [
      "invoices",
      "contacts:read"
    ],
    "scopesSummary": "invoices, contacts:read",
    "createdAt": "2026-02-19T12:00:00.000Z",
    "warning": "Store this key securely. It will not be shown again."
  }
}