Service-to-service authentication with long-lived API keys. Includes scopes, expiration, and usage tracking.

API Keys

API Keys provide secure, long-lived authentication tokens for service-to-service communication, CI/CD pipelines, and external integrations.

Key Format

fcms_{prefix}_{secret}

fcms_ — identifier prefix
{prefix} — 8-character hex identifier (visible in UI)
{secret} — 32-character hex secret

Example: fcms_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Important: The full key is shown only at creation time. Save it immediately.

Using API Keys

Include your API key in the X-API-Key header:

curl -H "X-API-Key: fcms_a1b2c3d4_..." \
  https://your-fastcms.com/api/v1/collections

const response = await fetch('https://your-fastcms.com/api/v1/collections', {
  headers: { 'X-API-Key': 'fcms_a1b2c3d4_...' }
});

import requests
response = requests.get(
    'https://your-fastcms.com/api/v1/collections',
    headers={'X-API-Key': 'fcms_a1b2c3d4_...'}
)

API Endpoints

Create API Key

POST /api/v1/api-keys
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "name": "CI/CD Pipeline Key",
  "scopes": "collections:read,records:*",
  "expires_at": "2025-12-31T23:59:59Z"
}

Response (201 Created):

{
  "id": "550e8400-...",
  "name": "CI/CD Pipeline Key",
  "key": "fcms_a1b2c3d4_e5f6a7b8c9d0...",
  "key_prefix": "fcms_a1b2c3d4_****",
  "scopes": "collections:read,records:*",
  "expires_at": "2025-12-31T23:59:59",
  "message": "Save this key securely. It will not be shown again."
}

List API Keys

GET /api/v1/api-keys
Authorization: Bearer {jwt_token}

Update API Key

PATCH /api/v1/api-keys/{key_id}
Authorization: Bearer {jwt_token}

{
  "name": "Updated Key Name",
  "active": false
}

Delete API Key

DELETE /api/v1/api-keys/{key_id}

Revoke All API Keys

POST /api/v1/api-keys/revoke-all
Authorization: Bearer {jwt_token}

Scopes

Scope	Description
`*`	Full access (default)
`collections:read`	Read collection schemas
`collections:write`	Create/update collections
`records:read`	Read records
`records:write`	Create/update records
`records:delete`	Delete records
`records:*`	All record operations
`files:read`	Read files
`files:write`	Upload files
`files:*`	All file operations

Security Best Practices

Never commit keys to source control — use environment variables or secret managers
Use descriptive names — include purpose and environment: "Production Sync Service"
Set expiration dates — rotate keys regularly
Limit scopes — follow the principle of least privilege
Monitor usage — check last_used_at for inactive keys, review last_used_ip

Key Rotation

# 1. Create new key
new_key = create_api_key(name="Production Key v2", scopes="*")

# 2. Update services with new key
# ... deployment process ...

# 3. Verify new key works
# ... testing ...

# 4. Delete old key
delete_api_key(old_key_id)

Error Responses

Error	Cause
Authentication required	Invalid or missing key
API key has expired	Key past its `expires_at` date
API key is disabled	Key has `active: false`
API key not found	Key ID does not exist

API Keys

On this page