> ## 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.

# OAuth for app builders

> Let CaptureFlow users connect your app with OAuth 2.1.

CaptureFlow runs its own OAuth 2.1 authorization server. MCP clients that follow the MCP authorization spec need nothing from this page: they discover everything from the metadata. Read on if you build your own client.

## Endpoints

| | |
| - | - |
| Issuer | `https://app.captureflow.ai` |
| Authorization server metadata (RFC 8414) | `https://app.captureflow.ai/.well-known/oauth-authorization-server` |
| Authorization | `https://app.captureflow.ai/oauth/authorize` |
| Token | `https://app.captureflow.ai/api/oauth/token` |
| Dynamic registration (RFC 7591) | `https://app.captureflow.ai/api/oauth/register` |
| Revocation (RFC 7009) | `https://app.captureflow.ai/api/oauth/revoke` |

Protected resources (RFC 9728), one per audience:

| Resource | Metadata |
| - | - |
| REST API `https://api.captureflow.ai` | `https://api.captureflow.ai/.well-known/oauth-protected-resource` |
| MCP server `https://mcp.captureflow.ai/mcp` | `https://mcp.captureflow.ai/.well-known/oauth-protected-resource/mcp` |
| Read-only MCP server `https://mcp.captureflow.ai/mcp/readonly` | `https://mcp.captureflow.ai/.well-known/oauth-protected-resource/mcp/readonly` |

A `401` from a resource carries `WWW-Authenticate: Bearer resource_metadata="..."`, the start of discovery.

## Identify your app

> [tab] Client ID metadata document (preferred)
>
> Use an `https` URL as your `client_id`, pointing to a JSON document you host:
>
> ```json theme={null}
> {
>   "client_id": "https://example.com/oauth/client.json",
>   "client_name": "Example",
>   "redirect_uris": ["https://example.com/oauth/callback"],
>   "token_endpoint_auth_method": "none"
> }
> ```
>
> The document's `client_id` must be its own URL, `token_endpoint_auth_method` must be `none` (no secret), with 1 to 10 `redirect_uris`. CaptureFlow fetches it (no redirects, 5 KB at most) and caches it for a day.

> [tab] Dynamic registration
>
> `POST /api/oauth/register` with `client_name` and 1 to 5 `redirect_uris`. Redirects must be `https`, or `http` on `localhost`, `127.0.0.1` or `[::1]` (any port). You get a `client_id` (`cfc_...`) and, unless you ask for `token_endpoint_auth_method: none`, a `client_secret` (`cfo_cs_...`). Unused registrations are removed after 30 days.

## Authorization code flow

1. Send the user to `/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope` (space-separated [scopes](https://docs.captureflow.ai/guides/scopes.md); unknown ones are ignored, and without any the app gets read-only access), `state`, `code_challenge` and `code_challenge_method=S256`, and `resource` (the resource you will call; the MCP server when omitted). PKCE with S256 is required.
2. The user signs in to CaptureFlow, picks a default workspace and approves, possibly narrowing the scopes. CaptureFlow redirects back with `code`, `state` and `iss` (RFC 9207).
3. Exchange the code at the token endpoint (form-encoded): `grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier`, `client_id` and the same `resource`. Codes last 10 minutes and work once.

The answer has an `access_token` (`cfo_at_...`, one hour), a `refresh_token` (`cfo_rt_...`) and the granted `scope`.

## Refreshing

`grant_type=refresh_token` returns a new pair; refresh tokens rotate. A refresh token reused within 30 seconds of its rotation (a retried request) gets one more pair; any later reuse revokes the whole sign-in, as a stolen token would be. A refresh token unused for 30 days expires, and a sign-in lasts at most 180 days before the user approves again.

## Revoking

`POST /api/oauth/revoke` with a token revokes the user's whole sign-in with your app. Users can also disconnect your app in **Settings > API & MCP > Connected apps**.

## Tokens are bound to a resource

A token works only for the `resource` it was issued for. A token for the MCP server also works on the read-only MCP server (with read scopes only); call the REST API with a token issued for `https://api.captureflow.ai`.


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