> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/platform/authentication.md).

# Authentication

Create, scope, use, rotate and revoke FLORA API keys, and keep them safe on your server.

The FLORA API uses bearer-token authentication with API keys. Every request carries your key in the `Authorization` header:

```http
Authorization: Bearer ak_XXXX
```

{% hint style="warning" %}
An API key holds the read, write and billing permissions you chose for each workspace it covers, and write lets it spend money. Never put it in front-end code, public repos or logs. Read it from an environment variable or a secrets manager.
{% endhint %}

Connecting an AI client such as Claude, ChatGPT or Cursor? Use [FLORA MCP](https://docs.flora.ai/mcp.md) instead. It signs you in with OAuth, so you don't paste a key into the client. See [FLORA MCP authentication](https://docs.flora.ai/mcp/authentication.md).

## Create a key

1. Sign in to [FLORA](https://app.flora.ai).
2. Open **Settings → API Keys**. If your workspace belongs to an organization, open **Settings**, choose the workspace under **Workspaces**, and select **API Keys** under **Security**.
3. Click **Create API Key**, give it a name, and choose the workspaces it can reach and its permissions in each.
4. Copy the key from the **API Key Created** dialog right away. It isn't shown again.
5. Store it in a secrets manager or an environment variable such as `FLORA_API_KEY`.

Workspace admins can always create keys. Whether editors can depends on two settings:

* **Allow editors to create API keys**, under **Access & Permissions** in the workspace's settings, lets editors create keys for that workspace.
* **Only admins can create API keys**, under **Settings → Workspaces → All → API key access**, overrides every workspace in an organization. While it's on, editors can't create keys in any of the organization's workspaces, and the workspace setting is locked. Keys that already exist keep working. Only organization admins see this setting.

The same dialog shows the webhook signing secret (`whsec_...`) for each workspace the key covers. Keep it if you plan to use [webhooks](https://docs.flora.ai/api/platform/webhooks.md).

If **API Keys** is missing from Settings or asks you to upgrade, your plan doesn't include API access. See [How FLORA pricing works](https://docs.flora.ai/plans-and-billing/pricing.md).

## Permissions

You choose permissions per workspace when you create the key. They're independent: write doesn't imply read.

| Permission  | Covers                                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Read**    | List and get endpoints: Techniques, projects, workspaces, assets, models, runs                                                         |
| **Write**   | Create, update and delete; uploads; starting generations and Technique runs (billed to the workspace in US dollars)                    |
| **Billing** | [Organization usage](https://docs.flora.ai/api/guides/organizations.md) and usage exports for the organization that owns the workspace |

`GET /workspaces` lists the workspaces where the key has read. A Technique list without `workspace_id` uses the key's default workspace; pass `workspace_id` to list another workspace the key covers. Keys created before per-workspace permissions existed keep full access to their original workspace.

What a key can't do:

* Manage billing, plans or members. Use the FLORA app.
* Open an agent session on a project (`POST /projects/{projectId}/agent-session`) if the key carries per-workspace permissions. Use OAuth, or a key created before per-workspace permissions existed.

A request outside the key's permissions returns `403 forbidden`. See [Errors](https://docs.flora.ai/api/platform/errors.md).

## Active key limit

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

1. Create the new key.
2. Switch your applications to it.
3. Revoke the old key.

## Use the key

{% tabs %}
{% tab title="TypeScript" %}

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

const client = new FloraClient({ apiKey: process.env.FLORA_API_KEY })
// Or omit apiKey: the client reads FLORA_API_KEY itself.
```

{% endtab %}

{% tab title="CLI" %}

```bash
export FLORA_API_KEY="ak_XXXX"
flora techniques list
```

{% endtab %}

{% tab title="curl" %}

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

{% endtab %}
{% endtabs %}

## Request IDs

Every response includes a `Flora-Request-Id` header that identifies the call in FLORA's logs. Capture it with `curl -i`:

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

Include it whenever you contact support about a specific request.

## Revoke a key

In **API Keys**, click **Revoke** next to the key. It stops working right away: later requests with it return `401` with the code `unauthorized` or `invalid_api_key`. Revoking can't be undone; create a new key to restore access.

## Suspected compromise

If you think a key has leaked:

1. Revoke it right away in FLORA.
2. Create a new key and update your applications.
3. Email <support@florafauna.ai> so FLORA can review recent activity on the old key.
4. If the key reached a public repo, treat it as compromised even after you scrub the history, because secret scanners may already have copied it.

## Security best practices

* **Server-side only.** Never ship a key in a mobile app, a single-page app, or anything a user downloads.
* **Environment variables or a secrets manager.** Never hard-code keys.
* **Least privilege.** Give each key only the workspaces and permissions it needs. A reporting job needs read or billing, not write.
* **Separate environments.** Use different keys, and ideally different workspaces, for staging and production.
* **Rotate regularly,** for example every 90 days, even without a known leak.

## Related

* [Errors](https://docs.flora.ai/api/platform/errors.md): `401 unauthorized`, `401 invalid_api_key` and `403 forbidden`.
* [Idempotency](https://docs.flora.ai/api/platform/idempotency.md): retry safely without duplicate runs.
* [FLORA MCP authentication](https://docs.flora.ai/mcp/authentication.md): OAuth for AI clients.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/platform/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
