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. |
Unknown scopes are stored as workspace. 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.