Authentication

All API requests require authentication using an API key.

API Keys

API keys are the primary method for authenticating with the Creed Space API.

Key Format

cs_live_abc12345_xK9mN2pQ7rS4tU6vW8xY0zA3bC5dE7fG9hI1jK3lM5nO7pQ9r
│  │    │        └─ 48 random characters (secret)
│  │    └─ 8 character prefix (for identification)
│  └─ Environment (live or test)
└─ Creed Space prefix

• Live keys (cs_live_*) - Production use, charges apply
• Test keys (cs_test_*) - Testing only, no charges, rate-limited

Creating API Keys

1. Go to Dashboard → API Keys
2. Click Create New Key
3. Enter a name and select permissions
4. Accept the Terms of Service
5. Copy the key immediately - it won't be shown again

Using API Keys

Include your API key in the request header:

curl -H "X-API-Key: cs_live_..." https://api.creed.space/api/v1/safety/evaluate

Or use Bearer token format:

curl -H "Authorization: Bearer cs_live_..." https://api.creed.space/api/v1/safety/evaluate

Key Management

Listing Keys

GET /api/v1/ssaas/keys

Returns all your API keys (prefix only, never the full key).

Revoking Keys

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

Immediately invalidates the key. This cannot be undone.

Rotating Keys

POST /api/v1/ssaas/keys/{key_id}/rotate

Creates a new key and schedules the old one for revocation. The old key continues to work for 5 minutes (grace period).

Scopes

API keys can be limited to specific permissions:

Scope	Description
*	Full access (default)
safety:evaluate	Call safety evaluation endpoint
safety:metrics	Read safety metrics
pdp:adjudicate	Call PDP adjudication
constitutions:read	Read constitutions
constitutions:write	Create/modify constitutions
billing:read	Read billing information

Security Best Practices

1. Never expose keys in client-side code - Use server-side proxies
2. Use environment variables - Don't hardcode keys
3. Rotate keys regularly - Use the rotation endpoint
4. Use minimal scopes - Only grant necessary permissions
5. Monitor usage - Check the dashboard for unusual activity

Error Responses

401 Unauthorized

{
  "error": "api_key_required",
  "message": "API key required. Include X-API-Key header or Bearer token.",
  "docs": "https://docs.creed.space/authentication"
}

403 Forbidden

{
  "error": "insufficient_scope",
  "message": "API key missing required scope: safety:evaluate",
  "required": "safety:evaluate",
  "available": ["constitutions:read"]
}

IP Whitelist Rejection

{
  "error": "ip_not_allowed",
  "message": "IP 203.0.113.42 not in whitelist for this API key."
}