API tokens
API tokens let users and service accounts call the Forra API programmatically. Every token is minted with a name and one or more scopes chosen from a fixed list — there is no raw path/verb editor in the UI.
Prerequisites
- Any user can mint a personal API token for themselves.
Organization Administratorrole is required to mint a service-account token.
1. Scopes restrict, they never grant
A token's scopes are a ceiling on its own owner's access, not a separate grant of capability. A token cannot do anything its owner could not already do through their own session. This means two things always have to be true together for an automation to work:
- The user or service account must hold whatever role the target action needs (for example, the
Organization Administratorrole for tenant-admin actions). - The token must carry the matching scope.
Selecting a scope that the owner cannot use is harmless — the token is simply unable to reach that surface, exactly as if the scope had not been selected.
2. Available scopes
| Scope | What it allows |
|---|---|
| Read your profile | Read your own preferences, custom prompt, connected services, usage and costs. Selected by default. |
| Modify your profile | Change your preferences and custom prompt. Your custom prompt affects every one of your assistants' answers. |
| Chat & conversations | Chat with assistants and manage the conversations this token works with. Cannot list conversation history. |
| Read all conversations | Read your entire conversation history, including conversations this token did not create. Cannot send messages. |
| Projects | Create and manage projects, and organize conversations into them. |
| OpenAI & Anthropic compatible APIs | Use the OpenAI-compatible and Anthropic-compatible endpoints. Only shown when at least one of those integrations is enabled for your tenant. |
| Read assistants | List assistants and read their configuration, skills, files and stored data. |
| Manage assistants | Create, modify and delete assistants, including running their functions and issuing embedded-app tokens. Sensitive. |
| Generate AI content directly | Generate images, audio, video and image analysis directly through the API. |
| Knowledge bases | Create and manage knowledge bases and their documents. |
| Tasks & automations | Create, run and manage automations, including scheduled ones. |
| Workflows | Create, run and debug workflows. |
| Memory | Read, create and delete the stored memory assistants use to personalize their answers. |
| Skills | Read and manage skills, including building an assistant's skills. |
| Read directory | Read the list of users, groups and teams in the organization. |
| Organization administration | Full administrative access to the organization. Sensitive — only grant this to a token that genuinely automates administration. |
Some scopes only appear when the corresponding feature is enabled for your tenant. Hiding a scope has no effect on tokens minted while it was visible — their behavior does not change.
3. Three distinctions worth knowing
- "Chat & conversations" cannot list your conversation history. It can send messages and read back a conversation it already knows the ID of, but it cannot enumerate everything you have ever said. Use "Read all conversations" for that.
- "Generate AI content directly" is not required for assistants to produce images or audio during a conversation. That happens internally and needs no extra permission. Grant this scope only to a token that calls the image/audio/video endpoints itself.
- "Modify your profile" can rewrite your custom prompt, which changes how every one of your assistants answers — treat it with the same care as any other sensitive scope.
4. Mint a token
Go to Settings → Security → API Tokens → Create. Enter a name, select the scopes the token needs, choose an expiry, optionally restrict assistants and external services, and confirm. The token's value is shown once — copy it immediately, since it cannot be revealed again afterward.
Minting is rejected if no scope beyond the default is selected — an API token that can only identify itself is rarely what you want.
5. Assistant restriction
When minting a token you can limit which assistants it can reach:
| Mode | Effect |
|---|---|
| All assistants (default) | The token reaches every assistant its owner can reach. |
| No assistants | The token cannot call any assistant endpoint. Conversations not tied to an assistant remain reachable. |
| Restricted to specific assistants | The token can only operate on the selected assistants. Calls to other assistants' endpoints are rejected. Conversations belonging to other assistants are also rejected. |
A token with no assistant restriction behaves exactly as before. Conversations that are not tied to any assistant remain reachable even when the token is restricted or set to no assistants.
The token list shows No assistants or Restricted to N assistant(s) when access is not unrestricted.
6. External services
When minting a token you can control which external services (OAuth integrations) it can use:
| Mode | Meaning |
|---|---|
| All external services | The token can use every external service configured for the tenant. |
| No external services (default for new scoped tokens) | The token cannot call any external service. |
| Restricted to specific services | The token can only use the selected services. |
External-service access is already enforced by the token system; the mint form only lets you choose which services are stored on the token.
The token list shows No external services or N external service(s) when access is not unrestricted.
7. Expiry
Every newly minted token has an expiry chosen from a fixed list of presets:
| Preset | Duration |
|---|---|
| 1 month | ~30 days |
| 3 months | ~90 days |
| 6 months (default) | ~180 days |
| 12 months | ~365 days |
| No expiration | Never expires |
The default is 6 months. A leaked token stops working on its own when it expires, instead of staying valid until someone notices and revokes it.
Tokens that carry a sensitive scope (Modify your profile, Read all conversations, Organization administration) cannot be set to No expiration. The option is disabled in the mint form when any of those scopes is selected.
The token list shows each token's expiry date, or Does not expire when none was set.
Existing tokens minted before expiry existed are unaffected — they remain non-expiring. Automation that previously relied on long-lived tokens will need rotation once new tokens start expiring.
8. Known limitations
- Read access to an assistant cannot be separated from read access to its stored data — the "Read assistants" scope grants both together. Assistant restriction (
allowed_assistant_ids) can still limit which assistants a token reaches, but within an allowed assistant the stored-data read is not separable from configuration read.
9. Legacy tokens
Tokens minted before scopes existed show a Full access (legacy) label instead of a scope list, since their rights were never recorded as scopes. Treat this label as a warning, not a feature: such a token has unrestricted access. Revoke it and mint a new, scoped token in its place.
Legacy tokens also have no assistant restriction — they reach every assistant their owner can reach.