> ## Documentation Index
> Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Bearer tokens, API keys vs OAuth, and how organization scoping works.

Every request must carry a bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer fe_k_<random_hex>
```

FlowEstate accepts two bearer types:

| Type                   | Format                          | When to use                                                              |
| ---------------------- | ------------------------------- | ------------------------------------------------------------------------ |
| **API key**            | `fe_k_` + 32 hex chars          | Server-to-server integrations, scripts, Make/Zapier "API Key" auth       |
| **OAuth access token** | Opaque token, no `fe_k_` prefix | End-user integrations connected through the FlowEstate Zapier / Make app |

## API keys

API keys are created in the FlowEstate dashboard under **Settings → API Keys**. The raw key is shown **once** at creation; FlowEstate stores only a SHA-256 hash. If you lose the key, revoke it and create a new one.

Each key carries:

* A **set of scopes** that limits what it can do (see [Scopes](/scopes)).
* An **organization binding** — every read and write is automatically restricted to that organization.
* An optional **expiration date**.
* An **active flag** — disable a key without deleting it to revoke access immediately.

There is no `organizationId` parameter to pass on any endpoint. The token is the source of truth.

## OAuth access tokens

If you're an end user connecting FlowEstate through the official Zapier or Make app, your bearer is an OAuth access token issued by FlowEstate's identity provider. You don't usually see this token directly — the connector handles it for you.

OAuth tokens behave the same as API keys from the API's perspective: same scopes, same organization scoping, same rate limits. The differences are operational:

* They're tied to a specific **user**, not the organization at large.
* They expire and refresh automatically.
* They can be revoked from **Settings → Connected Apps**.

## Authentication errors

| HTTP  | Code           | When                                                                                               |
| ----- | -------------- | -------------------------------------------------------------------------------------------------- |
| `401` | `UNAUTHORIZED` | Missing or malformed `Authorization` header, unknown key, expired OAuth token.                     |
| `403` | `FORBIDDEN`    | Key is inactive, expired, or missing a required scope; OAuth client disabled or unbound to an org. |

When troubleshooting, hit `GET /api/v1/me` with the same bearer — if that returns `200`, your authentication is fine and the issue is downstream (scopes, plan limits, validation). If `/me` itself fails, fix authentication first.

## Best practices

* **One key per integration**, named after the integration (`make-lead-ingest`, `zapier-pipeline-sync`). Easier to audit and revoke.
* **Minimum scopes**. Don't grant `leads:write` to a key that only reads.
* **Rotate periodically** — at minimum, when an employee leaves or a third-party platform is replaced.
* **Never commit keys to source control.** Treat them like passwords.
* **Set expirations** for short-lived integrations (one-off backfills, contractor work).