# Authentication

The Frontline Public API authenticates every request with a **Bearer API key**.


```http
Authorization: Bearer <YOUR_API_KEY>
```

Requests without an `Authorization` header, with a malformed header, or with an unknown/revoked key return `401 Unauthorized` (see [Errors](/docs/errors)).

## Key types

Frontline issues two kinds of API key. The type determines what an endpoint can do with it.

| Type | Scope | Use for |
|  --- | --- | --- |
| `GENERAL` | Account-level. No user identity. | Read-only integrations, dashboards, machine-to-machine sync. |
| `USER` | Bound to a single user in the account. | Any write that should be attributed to a person: creating agents, updating settings, publishing flows, building flow/workflow graphs, creating incoming webhooks, managing tools/variables/intents. |


Most endpoints accept **either** type. Endpoints that require a `USER` key are explicitly marked in their description in the **[API Reference](/reference/openapi)** ("Requires a USER API key").

If you call a `USER`-only endpoint with a `GENERAL` key, you get `401 Unauthorized`.

## Generating and managing keys

Both kinds of API key are created from inside the Frontline app, but they live in different places. Open the app, click your **user name in the bottom-left of the sidebar**, and choose **Settings** — from there, the flow splits by key type.

### Personal API key (`USER`)

1. In the settings sidebar, under **My settings**, open **Bring your own Agent**.
2. Click **Create personal API key**, name it (per agent / IDE is a sensible split), and confirm.
3. Copy the key immediately. The dashboard stores only a SHA-256 hash of the secret — it cannot be displayed again.


Each user can hold up to **5 personal keys** at a time. The same screen lists existing keys with their creation date and a delete button; remove an unused key to free a slot.

### Account API key (`GENERAL`)

1. In the settings sidebar, under **Account settings**, open **Developer**.
2. Click **Create API key**, give it a memorable name, and confirm.
3. Copy the key immediately — same one-time-display rule as above.


Account keys are not bound to a single user, so any teammate with workspace-admin access can create or revoke them. There is no fixed per-account cap.

### Rotating and revoking

- **Rotate**: create a new key, swap it into your client, delete the old one. There is no in-place rotation.
- **Revoke**: deleting a key invalidates it on the next request.
- A revoked or deleted key returns `401 unauthorized` with no grace period.


## Verifying a key

Hit `GET /public/v1/me` to confirm a key is valid and inspect what it represents:


```bash
curl https://prod-api.getfrontline.ai/public/v1/me \
  -H "Authorization: Bearer $FRONTLINE_API_KEY"
```


```json
{
    "ok": true,
    "data": {
        "account": { "id": 1234, "name": "Acme Inc.", "namespace": "acme" },
        "user": { "id": 56, "email": "you@acme.com" }
    }
}
```

`data.user` is `null` for `GENERAL` keys.

## Storage and transport

- Always send keys over HTTPS. The server only accepts TLS.
- Never embed keys in client-side code, public repos, or analytics events.
- In CI/CD, inject keys via secrets, not committed config.
- Prefer one key per integration/environment so revocation has minimal blast radius.


## CLI

The [`frontline` CLI](/cli) reuses the same API keys. `frontline auth login <api-key>` stores the key locally per-profile and reuses it for both the `frontline` and `max` binaries.