Authentication
Create and manage API keys, or sign a user in and use their session token.
Every request carries a bearer token:
Authorization: Bearer <token>Two kinds of token are accepted, with deliberately different access models.
| API key | Session token | |
|---|---|---|
| Belongs to | An application | A person |
| Looks like | flk_live_… | An opaque session string |
| Reaches | Only what its allowlist names | Whatever that person can already reach |
| Scopes apply | Yes | No |
| Revoked at | Settings → API Keys | Settings → Sessions |
Use an API key for a server or a scheduled job. Use session tokens when each end user has their own Flitch account, so you are not shipping one shared secret inside an app bundle.
API keys
Open at Settings → API Keys. Keys belong to the space you are currently in, and can never read across spaces.
Create a key
Click New key. Give it a name describing what will use it, so it is recognisable later in the list.
Choose an expiry
30 days, 90 days, 1 year, or no expiry. The default is 90 days. An expired key returns 401 naming the date it expired.
Flitch emails 14 days, 7 days, and 1 day before it lapses, so a live integration is never cut off without warning. The warning goes to whoever created the key, or to the space's admins if that person has since left. An expiry cannot be extended, so the way to keep something running is to rotate before the date, as below.
Choose a rate limit
60, 600, or 3,000 requests per minute. The default is 600. This protects the sources a key reaches more than it protects Flitch, so pick by what kind of client it is: a scheduled job needs far less than a map redrawing as someone pans it. See rate limits.
Choose scopes
data:readreads datasets, connection queries, and table rows.tables:writeinserts, updates, and deletes input-table rows.
A call outside a key's scopes returns 403. Grant only what the integration needs.
Choose what it can reach
Everything grants the whole space, including datasets added after the key was made. Only selected grants exactly what you tick, and anything else returns 403.
Pick datasets. Flitch derives the connection behind each one automatically, so a key can never end up able to read a dataset but not query its connection.
Copy the secret
The secret is shown once, on creation, and is not retrievable afterwards. Store it in your secret manager before closing the panel. If you lose it, revoke the key and create another.
Keys are created from the settings UI only. A key can never mint another key.
Rotating and revoking
Two keys can be live at once, so rotation needs no downtime: create the replacement, deploy it, then revoke the old one.
Revoke stops a key on its very next request, with no cache grace period. The row stays in a Revoked section so the record of what existed survives. Delete on a revoked key removes it permanently, along with its usage history.
Usage
The Usage tab shows requests per day and a breakdown per endpoint, per key. Use it to confirm a client is calling what you expect and to spot a loop before it hits the rate limit.
Traffic from session tokens is counted too, attributed to the person rather than a key. It is listed for members of the space you are viewing, and counts all of that person's API calls, so someone who belongs to two spaces appears in both.
Session tokens
For an app where each user signs in with their own Flitch account, sign in against the auth API and read the token from the set-auth-token response header. Store it in the platform keychain, not in a bundled file, and send it as the bearer on subsequent calls.
A session token carries the access its owner already has through space membership. Scopes and allowlists do not apply, because the person's membership is the boundary. Tokens appear in Settings → Sessions, so removing one user's access needs no separate step.
A session token is validated against the Authorization header alone. A request carrying an expired token will not quietly authenticate off a browser cookie that happens to be present.
Because a person can belong to several spaces, endpoints that are not scoped to a single resource need a teamId. Call /me first to list them.