Skip to main content
Fini API keys are workspace-scoped credentials for the public APIs documented in the API overview. Use them when an external service, backend job, BI pipeline, or internal tool needs programmatic access to Fini without going through a dashboard user session.
Workspace API keys currently use two scopes: read and write. The current Deploy → API Keys screen lets you choose either or both scopes, and the create form starts with both selected.

​
What an API key is in Fini

Every key:
  • belongs to a workspace, not to a single agent
  • is created by a specific teammate
  • can carry one or more scopes
  • is shown in plaintext once, at creation time
  • can be revoked individually
  • is sent as Authorization: Bearer <key>
The plaintext value starts with the fini_ prefix. In the dashboard list, Fini only shows a short prefix preview, never the full secret.

​
Scope model

Use least privilege:
  • Keep Write off for export-only or analytics-only workflows.
  • Include Write when the integration needs to send conversation events, ingest or refresh documents, or manage knowledge content.
  • Some read endpoints use POST, so pick scopes by endpoint purpose, not by HTTP method alone.

​
Create an API key

Open Deploy → API Keys in Fini.
1

Open the Create API key form

Click New API key at the top of the page.
2

Give the key a recognizable name

Use a name that tells you where the key is used, such as Warehouse export, Internal dashboard, or Zapier sync. The name is the only thing you’ll see in the table later, so be specific.
3

Choose the scopes

The form shows two checkboxes: Read and Write. Both are selected by default. Leave only the scopes this integration actually needs.
4

Click Create key

Fini generates the key and immediately shows the plaintext secret in a warning card, along with the scopes assigned to that key.
5

Copy and store it now

This is the only time the full key value is shown. Once you dismiss the warning card, you’ll only see the short prefix in the table.
If the key only needs to export data, uncheck Write before you create it. Separate keys with separate scope sets make revocation and incident response much easier.
If you lose the plaintext value, Fini cannot show it again. Create a new key and revoke the old one instead. There is no recovery flow.

​
Manage existing keys

The API Keys table shows one row per active key. Each row carries:
​
string
Your human-readable label for the key, set at creation time. The only identifier you’ll see day to day.
​
array
The permissions assigned to the key. The UI shows them as Read and Write chips.
​
string
The visible beginning of the key, for example fini_abc12…. Enough to match a key against a system that’s using it, never enough to reconstruct the secret.
​
string
The teammate who generated the key. Useful for asking “do we still need this?” when a teammate leaves.
​
datetime
When the key was created.
​
datetime | null
The most recent time the API accepted this key. If null or stale, the key is either unused or pointed at a system that’s broken.
Use separate keys for separate systems whenever possible. Rotation, debugging, and incident response all become easier when a single key maps to a single application.

​
Revoke a key

Click the trash icon on a row to revoke that key. Revoke is:
  • immediate, clients using the key stop authenticating on their next request
  • irreversible, the key cannot be reinstated; create a new one if you change your mind
  • scoped to that one key only, other keys in the workspace continue working
Any client still using the revoked key will start receiving 401 Unauthorized right away.

​
How to use a key

Send the key in the Authorization header as a Bearer token. The example below lists agents from the workspace tied to the key:
Do not send the key as x-api-key or as a query parameter. The public API guard expects an Authorization: Bearer header. Other transports will be rejected with 401 Unauthorized.
For the full endpoint list, request and response shapes, and error semantics, see the API reference.

​
Security best practices

Never ship a Fini API key in browser code, mobile app bundles, or anywhere a customer can inspect. Keys belong in your backend secrets manager, or environment variables on a server you control.
Avoid the shared-key anti-pattern. Separate keys for your warehouse export, your internal dashboard, and your Zapier flow means you can revoke or rotate one without breaking the others, and you can tell from the Last used column which system is calling.
Anyone who had access to a key in plaintext can still use it after they leave. Treat key revocation as part of offboarding. Same on the system side: when an integration is retired, revoke its key the same day.
If a key may have been exposed, committed to git, leaked in a log, or shared in a screenshot, revoke it immediately and create a replacement. Rotation is cheap, investigation later is not.
The name is the only thing standing between you and a row of indistinguishable fini_abc12… prefixes. Warehouse export, nightly cron, not key 3.

​
Troubleshooting

The full value is shown exactly once, at creation time. Create a new key and revoke the old one. There is no way to retrieve the plaintext later.
Check three things in order:
  1. The key hasn’t been revoked. Open Deploy → API Keys and confirm the key still appears in the table.
  2. You’re sending Authorization: Bearer <key>, not x-api-key and not a query parameter.
  3. The key value was copied fully, with no missing or extra characters. Bearer tokens are sensitive to truncation.
The endpoint likely requires a scope the key doesn’t have. Check the assigned scope chips on the key row. Write is required for conversation events, document ingestion, and knowledge-management mutations. Read is required for list, fetch, and status endpoints, even on a few routes that use POST.
The Last used timestamp only moves when a request reaches Fini successfully and authenticates with that key. If your client is failing before the request lands, DNS, TLS, wrong base URL, network egress blocked, the column won’t move even though you think the key is in use.