API keys

Objective. Create a workspace-scoped key with only the audience, bot access, and role an integration needs, then keep its full value out of browser code and source control.

Prerequisites

A workspace owner account. Only owners can create and revoke API keys.

Create a scoped key

1Open Settings → API keys. This section is available to workspace owners only.
2Choose a name that identifies the integration and its environment, such as warehouse-dashboard production or nightly reporting job.
3Choose the audience. Select REST API for /api/v1, MCP for /api/mcp, or Both when the same integration needs both surfaces. A REST-only key cannot call MCP, and an MCP-only key cannot call the REST API.
4Choose the bot scope. Leave the bot unset to authorize the workspace's bots, or pin the key to one bot. A pinned key returns 404 for every other bot.
5Choose the minimum role. Viewer reads bots, analytics, campaigns, bookings, catalog, and usage. Agent adds contacts and Inbox ticket work. Editor adds Operations, conversation history, campaign launch and cancellation, and appointment cancellation. Owner satisfies every current REST API requirement; it does not expose workspace settings through the REST API.
6Create the key, copy its full value into the integration's secret store, and confirm one request before distributing the integration.

Copy the secret once

A new key is shown exactly once. It begins with flu_; copy the full value before closing the confirmation. Fluenta stores a SHA-256 hash for verification and the leading 11 characters as the stored prefix for identification in Settings. The full value cannot be retrieved later.

REST request

curl "https://<your-host>/api/v1/me" \
  -H "Authorization: Bearer flu_..."

Revoke and rotate intentionally

1Revoke a key as soon as the integration is retired, a person or vendor no longer needs it, or you suspect it was exposed. Revocation stops subsequent requests immediately.
2For planned rotation, create a replacement with the same audience, bot pin, and minimum role. Put the replacement in the integration's secret store, verify a request, then revoke the old key.
3Keep the key only in a server-side secret manager, CI secret store, or similarly protected runtime configuration. Do not commit it, send it in support messages, or put it in browser JavaScript.

Expected result. The integration has a named API key with the smallest useful scope, its full value is stored only in the integration's secret store, and there is a documented replacement path before the key needs rotation.

Troubleshoot API key access

The REST API returns 401 unauthorized.: Send the complete key as Authorization: Bearer flu_.... Check that it was copied without spaces or truncation and has not been revoked. Create a replacement if the full value is no longer available.
The REST API returns 403 for a key that works with MCP.: The key is MCP-only. Create a key with the REST API or Both audience, update the server-side secret, verify the REST request, then revoke the old key if it is no longer needed.
The REST API returns 403 because the key role is too low.: Read the endpoint's minimum role in the REST API reference. Create a replacement with that role or higher, verify it, and revoke the old key when the integration no longer uses it.
A request to one bot returns 404 even though the key works for another bot.: The key is pinned to a different bot, or the target bot is outside the key's workspace. Use a key pinned to that bot or an unpinned workspace key. The API returns the same 404 response so a caller cannot distinguish those cases from an absent bot.