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

# Authentication

> API keys for scripts, OAuth 2.1 for apps your users connect. Both act for a CaptureFlow user.

Every call carries one credential in the `Authorization` header:

```http theme={null}
Authorization: Bearer cf_live_...
```

> [!WARNING]
>
> Never put a key or token in the URL. A request with `api_key`, `key`, `access_token` or `token` in the query string is refused with [`credentials_in_url`](https://docs.captureflow.ai/api/errors#credentials_in_url). Revoke that key: URLs end up in logs.

## API keys

For your own scripts, automations, and AI apps that can only send a header.

| | |
| - | - |
| Format | `cf_live_` followed by 38 characters |
| Created in | **Settings > API & MCP**, shown once |
| Permissions | *Read only*, *Read and create drafts* or *Full access* ([scopes](https://docs.captureflow.ai/guides/scopes.md)) |
| Workspace | All your workspaces, or locked to one ([workspaces](https://docs.captureflow.ai/guides/workspaces.md)) |
| Expiry | Never, 30, 90 or 365 days |
| Limit | 20 active keys per person |

A key acts as the person who created it. Revoke a key at any time in Settings; it stops working at once.

> [!TIP]
>
> For an AI app that stores the key in its settings, use a key limited to one workspace, with only the permissions it needs and an expiry date.

### Acting as a member (`as_user`)

An owner or admin can act as another member of the same workspace with an API key, by adding `as_user=<user id>` to the query. The call then reads and writes that member's content, as **View as** does in the app. Every such call is recorded. It is refused with [`as_user_forbidden`](https://docs.captureflow.ai/api/errors#as_user_forbidden) for anyone else, and is not available to connected apps or over MCP.

## Connected apps (OAuth 2.1)

AI assistants (Claude, ChatGPT, Cursor...) and apps you build connect through CaptureFlow's own OAuth 2.1 authorization server. The person signs in to CaptureFlow, sees what the app asks for, and can narrow it before approving.

* Access tokens look like `cfo_at_...` and last one hour; apps refresh them.
* Each token works only for the resource it was issued for: the REST API, the MCP server, or the read-only MCP server.
* People see and disconnect their apps in **Settings > API & MCP > Connected apps**.

Building an app? See [OAuth for app builders](https://docs.captureflow.ai/guides/oauth.md).

## Who am I?

`GET /v1/me` returns the user a credential acts for, its type (`api_key` or `oauth`), its scopes and the workspace it is locked to, if any.

## Errors

| Code | When |
| - | - |
| [`unauthorized`](https://docs.captureflow.ai/api/errors#unauthorized) | Missing, unknown, revoked or expired key or token. The response's `WWW-Authenticate` header points to the OAuth metadata. |
| [`insufficient_scope`](https://docs.captureflow.ai/api/errors#insufficient_scope) | The credential is valid but lacks the permission this call needs. |
| [`credentials_in_url`](https://docs.captureflow.ai/api/errors#credentials_in_url) | A credential was sent in the query string. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.