API Keys API

API keys provide an alternative to JWT tokens for programmatic access.

GET /api/api-keys

List all API keys for the organization. Requires api_keys:read permission.

[
  {
    "id": "uuid",
    "name": "CI/CD Pipeline",
    "key_prefix": "biz_live_abc",
    "scopes": {},
    "last_used_at": "2024-01-15T14:30:00Z",
    "expires_at": "2024-04-15T10:00:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "created_by_name": "John Doe"
  }
]

Note: The full key is never returned - only the prefix is shown for identification.

POST /api/api-keys

Create a new API key. Requires api_keys:write permission.

Request

{
  "name": "CI/CD Pipeline",
  "expires_in_days": 90
}

Response

{
  "id": "uuid",
  "name": "CI/CD Pipeline",
  "key": "biz_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "key_prefix": "biz_live_abc",
  "expires_at": "2024-04-15T10:00:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

Important: The full key is returned only once in this response. Store it securely - it cannot be retrieved again.

Expiration Options

expires_in_days	Description
30	1 month
90	3 months (recommended)
180	6 months
365	1 year
null	Never expires

DELETE /api/api-keys/{key_id}

Revoke an API key. Requires api_keys:write permission.

Returns 204 No Content.

Revoked keys can no longer be used for authentication. This performs a soft delete - the key record is retained with a revoked_at timestamp for audit purposes.

Using API Keys

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

curl http://localhost:8000/api/pipelines \
  -H "X-API-Key: biz_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Key Format

biz_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
├──────┘ └─────────────────────────────────┘
 Prefix              Random (32 chars)
(9 chars)

• Total length: 44 characters
• Prefix: biz_live_ (identifies as Bizon Platform key)
• Random: 32 characters from secrets.token_urlsafe(24)

Security

• Storage: Only the bcrypt hash is stored in the database
• Lookup: The key prefix (first 12 chars) is used for lookup
• Verification: Full key is verified against the bcrypt hash
• Audit: last_used_at is updated on each use
• Revocation: Soft delete via revoked_at timestamp

Permissions

API keys inherit the permissions of the user who created them:

Creator Role	API Key Permissions
Owner	Full access
Admin	Full access (except ownership)
Member	Create/edit pipelines
Viewer	Read-only

Best Practices

1. Use descriptive names - Include the use case (e.g., “GitHub Actions Deploy”)
2. Set expiration - Use 90 days for most use cases
3. Rotate regularly - Delete and recreate keys periodically
4. Limit scope - Create separate keys for different integrations
5. Monitor usage - Check last_used_at for unused keys
6. Revoke immediately - Delete compromised keys right away