# Authentication

Authenticate Form Plume API requests with an organization API key sent as a bearer token, choose between read and full scopes, and verify a key before using it.

Every [Form Plume API](/docs/api) request authenticates with an API key sent
as a bearer token:

```text
Authorization: Bearer fp_sk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Create keys in the dashboard under **API Keys** in the sidebar. Only
organization admins and owners can create, rename, reveal, or revoke them.

If an AI coding assistant is implementing the automation, give it the
[`form-plume-api` skill](https://formplume.com/skills/form-plume-api/SKILL.md).
Provide the key through `FORMPLUME_API_KEY` or a secret manager rather than
pasting it into the prompt.

## Scopes

You pick a scope when you create a key:

- **read** can call every GET endpoint. Write requests fail with a 403 and
  the code `read_only_key`, so a key wired into a dashboard or report can
  never modify anything.
- **full** can call everything on the API surface.

## How keys behave

Keys belong to the organization, not to the person who created them. They keep
working when someone leaves the team. An organization can hold up to 50 active
keys.

You can rename, revoke, and reveal keys again from the dashboard. Secrets
are stored encrypted rather than hashed, so you can recover a lost key
instead of rotating it.

To verify a key and see which organization it belongs to, call:

```bash
curl -s https://api.formplume.com/v1/api-keys/current \
  -H "Authorization: Bearer $FORMPLUME_API_KEY"
```

```json
{
  "key": {"id": "...", "name": "CI", "scope": "full", "key_prefix": "fp_sk_live_a1b2c3d4"},
  "tenant": {"id": "...", "name": "Acme", "plan": "pro"}
}
```

This is a cheap "does my key still work" probe. Put it at the start of
scripts and agent sessions so a revoked key fails immediately with a clear
error instead of halfway through a run.

## What API keys cannot do

Account-level endpoints reject API keys with a 403 and the code
`session_required`. That covers billing, organization membership, invitations,
avatar, and API key management itself. These endpoints only accept a
dashboard session.

So a leaked key can read or change form data within its scope, but it
cannot mint new keys, change who is in the organization, or touch billing.

> Treat API keys like passwords. Keep them in server-side configuration or a
>   secrets manager, never in browser code or a public repository. If a key
>   leaks, revoke it in the dashboard. Revocation takes effect immediately.

> API keys are not the per-form access keys that protect
>   [private forms](/docs/forms/private-forms). Access keys authorize
>   submissions to one form. API keys authorize management of the whole
>   organization.