Authentication

The evaluation and adjudication endpoints (/api/v1/safety/evaluate, /api/v1/pdp/adjudicate) authenticate with an API key. Account-management endpoints, including API key management below, need a signed-in dashboard session instead.

API Keys

Create and manage API keys from the Dashboard.

Key Format

cs_live_a1b2_xK9mN2pQ7rS4tU6vW8xY0zA3bC5dE7fG9hI1jK3lM5n
│  │    │    └─ 43-character URL-safe random secret
│  │    └─ 4 hex characters (key identifier, shown in the dashboard)
│  └─ Key type (live or test)
└─ Creed Space prefix

• Live keys (cs_live_*) - for production use
• Test keys (cs_test_*) - for development and testing

The prefix labels the key's intended use; both types have the same permissions and rate limits, and Creed Space does not charge per API call (see Rate Limits).

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 X-API-Key request header:

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

API keys must be sent in the X-API-Key header; Authorization: Bearer is reserved for dashboard session tokens and does not accept cs_ keys.

Gateway Keys for the SDKs

The Python and JavaScript SDKs call the tool-call gateway (/v1/...), which takes a different key: a crd_live_ or crd_test_ gateway key, sent as Authorization: Bearer. Mint one from the SDK tab in your account settings. Each account has one gateway key; minting a new one revokes the old one.

curl -H "Authorization: Bearer $CREED_GATEWAY_KEY" https://api.creed.space/v1/status

Key Management

Dashboard session required

The key-management routes below need a signed-in dashboard session (the session cookie set when you log in to creed.space, or a login JWT). They do not accept API keys: a call with X-API-Key or Authorization: Bearer cs_live_... returns 401 with {"error": "authentication_required", "message": "You must be logged in to access this resource"}. Most people manage keys from Dashboard → API Keys.

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 keeps working for the grace period: 60 minutes by default, set with grace_period_minutes (0 to 10080, that is up to 7 days). A key already in its grace period cannot be rotated again.

The easiest way to rotate is from Dashboard → API Keys: open the key and choose Rotate Key. Calling the endpoint directly needs a signed-in session, and the request body must accept the currently published Terms and Privacy Policy:

{
  "grace_period_minutes": 60,
  "legal_consent_accepted": true,
  "legal_consent_version": "<version>",
  "legal_consent_effective_date": "<YYYY-MM-DD>",
  "legal_terms_sha256": "<terms_sha256>",
  "legal_privacy_sha256": "<privacy_sha256>"
}

Copy the four values from GET /api/v1/consent/policy-status (fields version, effective_date, terms_sha256, privacy_sha256). A request without the acceptance, or with values that do not match the current publication, is rejected and no new key is created.

Scopes

API keys can be limited to specific permissions:

Scope	Description
*	All Access
safety:evaluate	Run safety evaluation against active constitutions
pdp:adjudicate	Request policy decisions with rationale and norm citations
constitutions:lint	Validate constitution syntax/semantics
vcp:audit	Query the VCP audit trail
vcp:context	Read and write VCP context tokens

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 Rotate Key on the key in Dashboard → API Keys
4. Use minimal scopes - Only grant necessary permissions
5. Monitor usage - Check the dashboard for unusual activity

Error Responses

API-key authentication (401) and scope (403) errors are returned as RFC 7807 application/problem+json responses. Each of these bodies also carries a trace_id; include it when contacting support. It is omitted from the examples below. Other errors, such as validation (422) and rate limits (429), use different shapes; see Error Handling.

401 Unauthorized

Returned with a WWW-Authenticate: ApiKey header. A request with no X-API-Key header:

{
  "type": "https://api.creed.space/problems/invalid-api-key",
  "title": "Invalid API Key",
  "status": 401,
  "detail": "API key is invalid.",
  "instance": "/api/v1/safety/evaluate",
  "error_code": "INVALID_API_KEY",
  "reason": "missing",
  "docs_url": "https://docs.creed.space/authentication"
}

The reason field distinguishes the cause: missing, invalid, format, expired, revoked, ip_not_whitelisted or origin_not_allowed.

403 Forbidden

{
  "type": "https://api.creed.space/problems/scope-required",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "API key missing required scope: safety:evaluate",
  "instance": "/api/v1/safety/evaluate",
  "error_code": "SCOPE_REQUIRED",
  "required_scope": "safety:evaluate",
  "available_scopes": ["vcp:context"]
}

IP Whitelist Rejection

A key with an IP whitelist, used from an address outside it, is rejected as an invalid key:

{
  "type": "https://api.creed.space/problems/invalid-api-key",
  "title": "Invalid API Key",
  "status": 401,
  "detail": "API key is not permitted from this IP address.",
  "instance": "/api/v1/safety/evaluate",
  "error_code": "INVALID_API_KEY",
  "reason": "ip_not_whitelisted",
  "docs_url": "https://docs.creed.space/authentication"
}