Authentication - clarife

API Keys

Every API request must include a valid API key. Keys are created in your clarife dashboard and scoped to specific permissions.

Creating a Key

Open Settings - Go to Settings > API in your clarife dashboard at my.clarife.app.
Click 'Create API key' - Give the key a descriptive name (e.g. "n8n integration" or "CI pipeline").
Select scopes - Choose which permissions the key should have. Follow the principle of least privilege - only grant what the integration actually needs.
Copy the key - Your key is displayed once. Copy it and store it securely. It starts with clrf_.

⚠️ Warning: API keys are shown only at creation time. If you lose a key, revoke it and create a new one.

Key Format

All clarife API keys consist of the clrf_ prefix followed by 64 hexadecimal characters:

clrf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The clrf_ prefix makes keys easy to identify in logs and secret scanners.

Authenticating Requests

Include the key in the Authorization header as a Bearer token:

bash

curl https://my.clarife.app/api/v1/documents \
  -H "Authorization: Bearer clrf_your_key_here"

Workspace Context

For team workspaces, include the X-Workspace-Id header to specify which workspace the request targets:

bash

curl https://my.clarife.app/api/v1/documents \
  -H "Authorization: Bearer clrf_your_key_here" \
  -H "X-Workspace-Id: a1b2c3d4-5678-90ab-cdef-1234567890ab"

ℹ️ Info: If you omit X-Workspace-Id, the request operates on your personal resources.

Scopes

Each API key can be granted one or more scopes. An endpoint returns 403 Forbidden if the key lacks the required scope.

Scope	Description
documents:read	List and read documents and their content
documents:write	Create, update, and delete documents
projects:read	List and read projects and folders
projects:write	Create, update, and delete projects and folders
shares:read	List and read share links and view stats
shares:write	Create, update, and delete share links
brandings:read	List and read branding configurations (Business plan)
media:write	Upload screenshots and media files
workspace:read	Read workspace info and member list
kb:read	Read Knowledge Bases, categories, and entries (Business plan)
kb:write	Manage Knowledge Base content and settings (Business plan)

Key Limits

Plan	Max API Keys
Pro	5
Business	20

Attempting to create a key beyond your plan limit returns a 403 with code KEY_LIMIT_REACHED.

Revoking Keys

To revoke a key, go to Settings > API, find the key in the list, and click Revoke. The key stops working immediately. This action cannot be undone.

💡 Tip: Rotate keys regularly. If a key may have been exposed, revoke it immediately and create a replacement.

Error Responses

Status	Code	Meaning
401	UNAUTHORIZED	Missing or invalid API key
403	INSUFFICIENT_SCOPE	Key lacks the required scope
403	PLAN_REQUIRED	API access requires a Pro or Business plan
403	KEY_LIMIT_REACHED	Maximum number of API keys for your plan
429	RATE_LIMITED	Rate limit exceeded