Skip to content
This site is under construction. Content, screenshots, and workflows may change at any time.

API keys

An API key is a team-owned server credential for the REST API. Each key can reach only the bots and operations you choose when you create it.

Open Settings > API Keys. The page lists your team’s keys, with New key in the header.

Before you start

  • Your role. Only Owners, Team Admins, and Bot Admins can view and manage API keys.
  • A place to store the key. Plan to keep it in your server’s environment or secret manager. The key is shown only once.

Create a key

  1. Start a new key. In Settings > API Keys, select New key.

  2. Name it. Enter a Name that says where the key is used, such as Customer portal. Names must be unique in the team.

  3. Choose bot access. Under Bot access, select the bots this key can use, or select All bots in this team, including future bots.

  4. Choose permissions. Under Permissions, keep only what the integration needs. Send chat messages and Request responses are selected by default. See Permissions.

  5. Allow sessions if needed. Select Issue browser and mobile sessions only if your server will issue session tokens for a browser or mobile app.

  6. Create and copy. Select Create key, then Copy key. Store it on your server now. “It cannot be revealed again; a lost key must be revoked and regenerated.”

New API key

The New API key dialog has these fields. “Keep this key on your server. Its permissions also limit any client sessions it issues.”

SettingWhat it does
NameIdentifies the key in the list. Required and unique in the team.
Bot accessThe bots the key can call. All bots in this team, including future bots also covers bots you create later. Otherwise, select at least one bot.
PermissionsThe operations the key can perform. Select at least one.
Issue browser and mobile sessionsLets your backend issue 15-minute session tokens for individual users. “Sessions cannot exceed this key’s permissions or the API channel’s allowed actions.”

You can’t change a key’s name, bots, or permissions after you create it. To change access, create a new key, switch your integration to it, then revoke the old one.

Permissions

PermissionWhat it allows
Send chat messagesPOST /chat: start and continue conversations.
Request responsesPOST /responses: standalone answers, or continuing a /chat conversation.
Read conversation historyGET /bots/{bot_id}/chats/{chat_id}/messages: read a conversation’s messages.
Stream conversation eventsStreamed answers ("stream": true) on /chat and /responses.
Submit feedback/feedbacks: rate answers in API conversations.

Key list

Each key in the list shows:

ItemWhat it shows
NameThe name you gave the key, with a Revoked badge after you revoke it.
Masked keyThe key’s prefix and last four characters, such as fct_live_••••a1b2.
Last usedWhen the key last authenticated a request, or never. It updates at most once a minute.
Access summaryAll team bots or the number of selected bots, then All API operations or the operation names, such as chat, responses. Keys that can issue sessions also show Can issue client sessions.
RevokeTurns the key off.

Key prefixes

PrefixMeaning
fct_live_A current key.
fbt_live_A key created before the FluentChat rename. These show All team bots · All API operations.

Keys that start with fbt_ still authenticate, but only in the X-Api-Key header. The Authorization: Bearer header accepts only keys that start with fct_, and the API Console sends test requests only with fct_ keys. To use Bearer authentication, create a new key and revoke the old one.

Revoke a key

  1. Find the key. In Settings > API Keys, find the key by name and masked value.

  2. Revoke it. Select Revoke, then confirm. “Any integration using this key will stop working immediately. This cannot be undone.”

Revoking a key also ends every session token it issued. Revoked keys stay in the list.

Keep keys safe

  • Store keys on your server only. Use environment variables or a secret manager. Never ship a key in website JavaScript, a mobile app, or a public repository.
  • Use session tokens for apps. Browser and mobile apps get 15-minute session tokens from your server instead of the key.
  • Use one key per integration. Separate keys let you revoke one integration without breaking others.
  • Grant the least access. Select only the bots and permissions each integration uses.
  • Revoke keys you no longer use. Check Last used to find idle keys.

FluentChat stores only a hash of each key. Nobody, including your team, can view a key again after the creation dialog closes.

Limitations

  • A key is shown once. If you lose it, revoke it and create a new one.
  • Keys can’t be edited. Create a new key to change its name, bots, or permissions.
  • Revoking can’t be undone. A revoked key never works again.
  • Requests are rate limited. Each key can make 300 requests per minute, and each IP address 120 requests per minute.

Troubleshooting

Could not load API keys.

Possible cause: Your role can’t manage API keys.

Solution: Ask an Owner, Team Admin, or Bot Admin to create the key, or to change your role.

The Create key button stays disabled

Possible cause: The key has no name, no bot selected, or no permission selected.

Solution: Enter a Name, select at least one bot or All bots in this team, including future bots, and select at least one permission.

bot_forbidden

Possible cause: The request’s bot_id isn’t in the key’s Bot access.

Solution: Use a key with access to that bot, or create one.

operation_forbidden or stream_forbidden

Possible cause: The key doesn’t have the permission for the endpoint, or for streaming.

Solution: Check the access summary in the key list. Send "stream": false, or create a key with the missing permission.

Next steps