API keys

A workspace API key is the credential your servers, scripts and integrations use to call the Jelliu REST API and the MCP server. This page is the operational deep dive: how a key is born, what each scope can and cannot reach route by route, how revocation propagates, how to rotate with zero downtime, and how to audit who did what with which key.

For the header format and the basic error responses, start with Authentication.

How it works

Every request passes three independent gates, in this order:

1. Authentication. The bearer value must be jl_ followed by exactly 64 lowercase hex characters. Jelliu hashes it with SHA-256 and looks it up. Unknown, revoked or expired keys, and keys whose workspace was deleted, are refused with 401.
2. Scope by HTTP method. Applied to every /api request. GET, HEAD and OPTIONS need read, write or full. POST, PUT, PATCH and DELETE need write or full.
3. Role gate per route. Routes restricted to workspace roles check the key again. On routes that no ordinary member can use (admin, owner or billing only), only a full key passes.

Some credential-management routes add a fourth gate that refuses every API key, including full. See Dashboard-only operations.

Three kinds of credential

Jelliu issues three unrelated credentials. They are not interchangeable, and each one is accepted only where listed.

The key object

GET /api/api-keys returns the workspace’s non-revoked keys, newest first. The secret is never included; only its public prefix.

{
  "data": [
    {
      "id": "3f6c2a8e-1b7d-4e5f-9a0c-2d4e6f8a1b3c",
      "tenant_id": "9b2e4d6f-8a1c-4e3b-a5d7-c9e1f3a5b7d9",
      "agent_id": null,
      "name": "CRM sync (production)",
      "prefix": "jl_0f9e8d7c",
      "scopes": ["read", "write"],
      "created_by": "user_2abcDEFghiJKLmnoPQR",
      "last_used_at": "2026-09-14T15:41:02.118Z",
      "expires_at": null,
      "revoked_at": null,
      "created_at": "2026-09-01T12:00:00.000Z",
      "usable": true
    }
  ]
}

Lifecycle

Keys also stop working when the workspace is deleted.

Limits on keys

Expired keys that have not been revoked still count toward the 25. Revoke them to free the slot.

What each scope can reach

The matrix below is derived from the gates applied to each route. “Member-level” routes are those a workspace member can use in the dashboard; “admin-exclusive” routes are those only an admin, owner or billing user can use.

How a refusal looks

A key that lacks the method’s scope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks the 'write' scope required for this operation"
  }
}

A read or write key on an admin-exclusive route:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This operation requires an API key with the 'full' scope"
  }
}

Dashboard-only operations

These routes refuse every API key, whatever its scope, so a leaked key can never mint new credentials or switch off the controls meant to contain a leak:

The response is 403 FORBIDDEN:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This action requires a signed-in admin session — API keys cannot perform credential-management operations."
  }
}

Workspace sign-in policies do not apply to keys

If the workspace requires MFA or SSO for its members, that requirement applies to people signed in to the dashboard. API keys are machine credentials and pass through it, so hardening your members’ sign-in never breaks integrations.

Keys that belong to an agent

Jelliu also issues credentials for its own use: the tool gateway your voice and chat agents call during a conversation, and the short-lived access tokens of MCP OAuth connections. These credentials:

• are named with the reserved internal: prefix, are hidden from GET /api/api-keys and do not count toward the 25-key limit;
• when bound to a specific agent, can never carry the full scope, and stop authenticating as soon as that agent is deleted;
• for MCP OAuth, expire after one hour and never exceed the role of the person who approved the connection.

You cannot create, list or revoke them through the API. That is why agent_id is always null on the keys you manage.

Rotating a key without downtime

A workspace can hold up to 25 keys at once, and every key works independently, so rotation is a matter of overlapping two keys.

curl -sS "https://api.jelliu.co/api/api-keys" \
  -H "Authorization: Bearer $JELLIU_ADMIN_API_KEY"

jl_0f9e8d7c idle for 14.2 minutes

If a key leaks

1. Revoke it first, from Settings → API Keys. Do not wait until the replacement is deployed if the key was exposed publicly.
2. Create a replacement and deploy it.
3. Review what the key did. Every audited request records the key as apikey:KEY_ID (see below).
4. If the key had full scope, also review outbound webhooks, WhatsApp templates, integrations and billing activity, which only full keys can change.

Auditing keys

Creation and revocation events

Creating and revoking a key each write an audit record with resource_type api_key and action api_key.create or api_key.revoke. The record carries the key’s public identity only: its id, prefix, scopes and expiry, who issued or revoked it, and, on creation, admin_equivalent: true when the key has the full scope. The secret and its hash are never written to the audit log.

curl -sS "https://api.jelliu.co/api/audit?resourceType=api_key&limit=20" \
  -H "Authorization: Bearer $JELLIU_ADMIN_API_KEY"

{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "tenant_id": "9b2e4d6f-8a1c-4e3b-a5d7-c9e1f3a5b7d9",
      "user_id": "user_2abcDEFghiJKLmnoPQR",
      "action": "api_key.create",
      "resource_type": "api_key",
      "resource_id": "3f6c2a8e-1b7d-4e5f-9a0c-2d4e6f8a1b3c",
      "ip_address": "203.0.113.24",
      "user_agent": { "browser": "Chrome", "os": "macOS", "device": "desktop" },
      "created_at": "2026-09-01T12:00:00.000Z"
    }
  ]
}

The list omits the changes payload. Fetch one entry with GET /api/audit/{id} to see the prefix, scopes and expiry that were recorded. limit accepts 1 to 100 (default 50) and offset pages through older entries.

What a key did

Audited requests made with an API key are recorded with user_id set to apikey: followed by the key’s id. Filter on it to see a single key’s activity:

curl -sS "https://api.jelliu.co/api/audit?userId=apikey:3f6c2a8e-1b7d-4e5f-9a0c-2d4e6f8a1b3c" \
  -H "Authorization: Bearer $JELLIU_ADMIN_API_KEY"

Alert on new keys in real time

Subscribe a webhook to audit.log_recorded with the auditActions filter set to api_key. to receive a signed event whenever a key is created or revoked. Remember that audit.log_recorded is not included in "*" and must be named explicitly. See Webhooks.

curl -sS -X POST "https://api.jelliu.co/api/webhooks" \
  -H "Authorization: Bearer $JELLIU_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://siem.example.com/hooks/jelliu",
    "events": ["audit.log_recorded"],
    "filters": { "auditActions": ["api_key."] },
    "description": "Credential changes"
  }'

Errors

Security best practices

• Least privilege. read for reporting and BI, write for integrations that add contacts or send messages, full only for automation that manages campaigns, webhooks, billing or compliance.
• One key per integration and environment. Separate keys make last_used_at meaningful, let you revoke one integration without touching the others, and make the audit trail attributable.
• Keep keys server-side. Never ship a jl_ key to a browser or mobile client. For a website chat, use the widget and its public widget ID.
• Store keys in a secret manager, inject them as environment variables, and keep them out of logs. The 8-character prefix is enough to identify a key in logs and tickets.
• Watch for idle and expired keys. Periodically list keys and revoke any whose last_used_at is old or whose usable is false.
• Alert on credential changes with an audit.log_recorded webhook filtered to api_key..
• For AI assistants, prefer OAuth. A connector that signs in through MCP OAuth receives one-hour tokens tied to the approving person, instead of a long-lived key pasted into a config file.

Related