Authentication

The Coherence public API authenticates with a workspace API key sent as a bearer token. First-party app traffic may instead present a session JWT, but for integrations and agents you'll use an API key.

API keys

When to use

Use API keys for:

• Backend integrations
• Automated scripts
• Server-to-server communication
• AI agents and MCP clients

Creating an API key

1. Go to Settings → API Keys
2. Click Create API Key
3. Name your key (e.g., "Production Integration")
4. Optionally select scopes (see below)
5. Copy and securely store the key — it is shown only once

Using API keys

Include the key in the Authorization header:

curl -X GET "https://api.getcoherence.io/v1/me" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

All keys use the sk_live_ prefix.

Verifying a key

Call GET /v1/me; a 200 returns the user, account, role, and scopes the key resolves to:

curl -X GET "https://api.getcoherence.io/v1/me" \
  -H "Authorization: Bearer sk_live_abc123xyz789"

{
  "userId": "...",
  "accountId": "...",
  "roleSlugs": ["owner"],
  "authMethod": "api_key",
  "apiKeyId": "...",
  "scopes": ["workspace:read", "records:read", "records:write"]
}

Scopes

A key may be created with one or more scopes. A key with no scopes inherits the creating user's role permissions. A key with scopes must hold the scope an endpoint requires.

Scopes used by the REST API today:

The full catalog you can select when creating a key also includes collab:read, collab:write, agents:read, schema:write, files:read, and files:write. These are enforced on other Coherence surfaces that accept the same keys (such as the MCP server); no REST endpoint requires them today.

Rotating keys

There is no single rotate endpoint yet, so rotation is a create-then-revoke sequence — at no point does your integration go without a valid key:

1. Go to Settings → API Keys and create a new key with the same scopes
2. Deploy the new key to your integration and verify it works (GET /v1/me)
3. Revoke the old key

Because revocation is immediate, always deploy and verify the new key before revoking the old one.

Revoking keys

To revoke an API key:

1. Go to Settings → API Keys
2. Find the key
3. Click Revoke

Revocation is immediate — all requests using that key will fail.

Security best practices

Do:

• Store keys in environment variables or a secret manager
• Use the narrowest scopes a key needs
• Rotate keys regularly and revoke unused keys

Don't:

• Commit keys to source control
• Share keys in plain text

Errors

Error responses use the standard envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "statusCode": 401
  }
}

Related: API Overview