API keys and app tokens

Fresco BI has two kinds of secret keys. Both are shown once, when you create them.

	API key	App token
For	Your own scripts that call the Fresco BI API	Your server, to embed reports in your website or app
Belongs to	You, in one organization	A workspace
Can do	What you can do, never more, narrowed by its scopes	Make short-lived embed tokens for the reports you pick
Who creates it	Any member, when the organization allows API keys	Workspace Admins, and organization Owners and Admins
Where	Account menu › API keys	Workspace › App tokens in the left menu

API keys

Before you start

The organization must allow personal API keys. When it does not, the API keys item is missing from the account menu and the page says This organization does not allow personal API keys.

Create an API key

1. At the bottom of the left menu, click the row with your avatar and name, then API keys.
2. Click New key.
3. Fill in the form:
   • Name: up to 100 characters, so you know what the key is for.
   • Scopes: tick what the key may do: reports:read, data-tables:read, data-tables:refresh, exports:create.
   • Expires: 7, 30, 90 or 365 days. There is no key without an end date.
   • Allowed IPs: optional. One CIDR range per line, for example 203.0.113.0/24, up to 20. The key then works only from those addresses.
4. Click OK.
5. The new key appears with Copy the key now. You won’t see it again. Copy it and keep it in a safe place.

Caution

Treat an API key like a password. Never paste it into code you share, a ticket or a chat. If it leaks, revoke it at once.

Use an API key

Your script sends the key in the Authorization: Bearer <key> header. Each request runs as you, with your current roles and row-level security, and only within the key’s scopes.

• You can have up to 10 active keys in an organization.
• Each key can make up to 60 requests a minute.

The API reference is coming soon.

See and revoke your keys

The list shows each key’s Name, Scopes, its last 4 characters (fbi_…), when it Expires, and when it was Last used and from which address.

To stop a key, click Revoke and confirm. Scripts that use it stop at once. A revoked or expired key shows Revoked or Expired; make a new key instead.

A key also stops working when you leave the organization, or when the organization stops allowing API keys.

App tokens

App tokens are for secure embedding: your server trades the app token for a short-lived embed token, and your web page shows the report with it. Row-level security applies. See Embed reports.

Before you start

• You need to be an Admin of the workspace, or an Owner or Admin of the organization. Others see Only workspace admins manage app tokens.
• App tokens work on every plan.

Create an app token

1. In the left menu, open Workspace › App tokens. You can also open it from a report: Embed, Secure embed (app token), then Open workspace App tokens.
2. Click New app token.
3. Fill in the form:
   • Name: up to 100 characters.
   • Scope: All reports in the workspace, or Chosen reports and pick up to 100 reports.
   • Expires after: 30, 90, 180 or 365 days.
   • Allowed websites (optional): one origin per line, for example https://portal.example.com, up to 20. Use https://; http:// works only for localhost. Leave it empty to allow any website.
4. Click New app token in the dialog.
5. Copy the token from New app token. It is shown once.

Caution

Keep the app token on your server. Never send it to a browser or put it in a web page.

A workspace can have up to 20 active app tokens. Every action on app tokens is written to the audit log.

Use an app token

Your server calls POST /api/embed/token with the app token. It gets back an embed token that lasts up to 60 minutes. Your page passes that embed token to the report frame. The Embed dialog of a report shows sample code for both sides.

Rotate or revoke an app token

The list shows each token’s name and last 4 characters, its Scope, when it Expires, when it was Last used, and its Status: Active, Revoked or Expired.

• Rotate makes a new secret and revokes the old one at once. Copy the new one and update your server.
• Revoke stops the token. Every embed token made from it stops at once.

Tick Show revoked tokens to see revoked tokens too.