API Keys
Create and manage API keys for programmatic access to Confluye.
API keys authenticate requests to the Confluye REST API. Workspace, personal, and copilot keys are scoped to one workspace. An organization key carries a workspace selection and a permission level and is accepted by the MCP endpoints for every selected workspace.
Creating, listing, and revoking keys in the app uses session routes under /api/api-keys. Those
routes require Admin or Owner. There is no /api/v1 create-key endpoint.
Creating an API key
Create keys in Settings → API Keys. Give the key a name (required; unique per scope inside the workspace, compared case-insensitively after trim) and choose a scope:
| Scope | Stored value | Use |
|---|---|---|
| Workspace | workspace | Default. Required for execute, credential CRUD, members, mailer, files, and other workspace-only v1 routes. |
| Personal | personal | Documented safe reads (workspace metadata, workflows, runs, schedules, notifications, custom tools, and MCP servers) use workspace-safe.v1; other routes reject the key (403). |
| Copilot | copilot | The same documented safe reads use workspace-safe.v1; mutations, secret reads, and execution require a workspace key (403). |
| Organization | organization | Created with organization: { workspaceSelection: "organization" \| "selected", workspaceIds, permission: "read" \| "write" }, validated against the creator's accessible workspaces. Accepted only by the organization MCP endpoint and by workspace MCP endpoints inside the selection; every other bearer route (REST v1, A2A, workflow runs) refuses it (403). Not anchored to a workspace: it stays valid when the creator leaves the workspace it was created from, and any Admin/Owner of a workspace in the organization can list, rename, or revoke it there. The permission is a ceiling intersected with the user's live role; scope cannot be changed afterwards. Never carries AIMS service-token assurance. |
| Product gateway | end_user_gateway | Only when the deployment enables end users. Created through the session API with permissions (a non-empty list of run, erase and export, or the dedicated memory permission alone; erase and export never share a key, and memory is never combined with another permission). A key with run or memory needs allowedWorkflowIds containing at least one workflow of the workspace; an erase-only or export-only key may omit it or use an empty list. Not offered in the create dialog; the API keys list shows each gateway key's permissions. With run it runs only those workflows on behalf of an end user of your product, recovers a lost execute response through the scoped delegation lookup, reads and cancels only its own runs through /api/v1/end-users/runs/{id}, and requests website or mailbox connection links, polls link status, and lists, reads or disconnects mailboxes. With erase it erases an end user, every end user of a tenant prefix, or a subject; with export it exports one end user's data; with memory it lists, corrects, classifies and deletes the remembered facts of the one end user a request names, in the memory resources connected to its allowed workflows, and it can run no workflow or skill. It reaches only its own workspace. Keys created before permissions existed are backfilled once to run and erase, and cannot export; no existing key gains memory. New keys require explicit permissions; missing or malformed stored permissions are denied. The unfiltered run listing, every other v1 route, and the MCP endpoints refuse it (403); a route answers 403 with code: "gateway_permission_required" when the key lacks its permission. Scope, allowlist and permissions cannot be changed afterwards. See End users. |
Unknown scopes in create/update payloads are rejected with a validation error. Only an omitted scope on
creation defaults to workspace; omitting scope on update leaves it unchanged. Authentication rejects an
unrecognized scope already stored on a key; it never upgrades that key to workspace access.
The same display name may exist once per scope
(a workspace key and a personal key can share a name).
Tokens are generated as hise_ plus 24 random bytes (base64url). Verification ignores tokens that
do not start with hise_.
Using an API key
Send the token as a bearer token. There is no X-API-Key header for Confluye API auth
(bearerTokenFromRequest only reads Authorization: Bearer).
curl https://confluye.run/api/v1/workflows \
-H "Authorization: Bearer hise_xxxxxxxxxxxxxxxxxxxxxxxx"
A missing, malformed, unknown, or revoked token — or a key whose user is banned or no longer a
workspace and organization member — authenticates as no key (401
{ "error": "Valid bearer API key is required" }). Successful verification updates lastUsedAt.
Endpoints that require scope === "workspace" return 403
{ "error": "A workspace API key is required." }. Cross-workspace resource ids typically return
403 ("API key cannot access this …") or 404. See the
API Reference.
Rotating and revoking
To rotate, create a new key and delete the old one. Revoke from the API Keys list (trash /
DELETE /api/api-keys/{id}). Deletion is immediate and audited as api_key.revoke (severity
critical).
/api/v1 does not apply a global request rate limit. Sign-in email and MCP OAuth endpoints
have their own limiters. Do not treat “no v1 rate limit” as permission to share keys widely.