Authentication

The FLORA REST API uses bearer-token authentication with API keys. Every request must include an Authorization header.

Authorization: Bearer ak_XXXX

Caution

API keys grant the read, write, and billing permissions you choose for each workspace they’re scoped to. Never expose them in frontend code, public repos, or logs. Use environment variables or a secrets manager.

For interactive agents (Claude, Cursor, VS Code), use the MCP/OAuth flow instead — it doesn’t require pasting an API key into the client.

Create a key

1. Sign in to FLORA.
2. Open Settings → API Keys, or go directly to https://app.flora.ai/projects?openSettings=true&initialTab=apiKeys.
3. Click Create API Key, give it a name, and copy the secret immediately. It is shown only once.
4. Store it in a secrets manager or set it as an environment variable.

Keys begin with ak_.

At creation you choose which of your workspaces the key can access and which permissions it holds in each. Read covers list and get endpoints, write covers create/update/delete, uploads, and running generations and techniques, and billing covers the organization usage and export endpoints for the organization that owns the workspace. GET /api/v1/workspaces lists the workspaces where the key has read access. The permissions are independent: write does not imply read. Existing keys retain full access to their original workspace. Omitting workspace_id from a technique listing uses the key’s default workspace; pass it explicitly to list another granted workspace.

Agent browser sessions act as the whole user, so only OAuth credentials and API keys created before per-workspace permissions existed can create them; keys that carry a permission map are refused. FAUNA chat requires both read and write on the project’s workspace.

Active key limit

You can hold up to five active API keys, and their workspace scopes may overlap. To rotate a key without downtime:

1. Create the new key in Settings → API Keys.
2. Update your applications to use the new key.
3. Revoke the old key.

Use the key

TypeScript

import { FloraClient } from "@flora-ai/flora"

const client = new FloraClient({
  apiKey: process.env["FLORA_API_KEY"],
})

CLI

export FLORA_API_KEY="ak_XXXX"
flora techniques list

curl

curl https://app.flora.ai/api/v1/techniques \
  -H "Authorization: Bearer $FLORA_API_KEY"

Identifying which key made a request

Every response includes a request-id header. The request ID uniquely identifies the call in our logs and tells you which key was used. Capture it:

curl -i https://app.flora.ai/api/v1/techniques \
  -H "Authorization: Bearer $FLORA_API_KEY"

Look for request-id: req_... in the response. Include this when contacting support about a specific request.

What the key can do

An API key is limited to the workspaces and permissions it was created with:

Capability	Allowed
List and read all resources (Techniques, Projects, Workspaces, Assets, Models)	Workspaces where the key has read
Create runs (billed in USD to the workspace)	Workspaces where the key has write
Upload assets	Workspaces where the key has write
Create or modify Projects	If the workspace allows it and the key has write
Organization usage and exports	If the key has billing on a workspace in that org
Manage billing or members	No (use the FLORA app)

Permission-restricted operations return 403 forbidden. See Errors.

Revoke a key

In Settings → API Keys, click Revoke on the key. The key stops working immediately — any in-flight or subsequent request with that key returns 401 invalid_api_key.

Revocation is irreversible. To restore access, create a new key.

Suspected compromise

If you think a key has leaked:

1. Revoke it immediately in the FLORA app.
2. Create a new key and update your applications.
3. Contact support — we can audit recent activity tied to the compromised key.
4. If the leak was a public repo, scrub git history with git filter-repo and force-push (treat the key as compromised even after scrubbing — secret scanners may have already cached it).

Security best practices

• Server-side only. Never embed keys in mobile apps, single-page apps, or anything that ships to a user.
• Environment variables. Read keys from process.env or a secrets manager (1Password, AWS Secrets Manager, GCP Secret Manager, Vault) — not hardcoded.
• Separate environments. Use a dedicated production workspace + key for production traffic. Don’t share a single key across staging and prod.
• Rotate periodically. Even without a known compromise, plan a rotation every 90 days.
• Limit blast radius. If you have multiple use cases, each in its own workspace, keys are naturally isolated.

Related

• Errors — what auth failures look like (401 unauthorized, 401 invalid_api_key, 403 forbidden).
• Idempotency — retry safely without duplicate side effects.
• MCP authentication — OAuth flow for interactive agents.