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

# Authenticate PanoFlow API requests

> Authenticate with PanoFlow using bearer API keys (pk_live_ and pk_test_) limited by scopes, or OAuth 2.1 with PKCE for third-party apps and AI agents.

PanoFlow authenticates every API request with a bearer credential in the `Authorization` header: a server API key for your own integration, or an OAuth 2.1 access token for apps and AI agents acting for a business. Each credential carries scopes that decide which operations it can call.

## API keys

API keys start with `pk_live_` (live) or `pk_test_` (sandbox). You create, scope and revoke keys in the PanoFlow web app; key management is not part of the public API.

Send the key as a bearer token on every request:

```bash theme={null}
curl https://api.panoflow.io/v1/balances \
  -H "Authorization: Bearer pk_live_..."
```

> [!WARNING]
>
> API keys are server credentials. Keep them out of browsers, mobile apps and source control.

A request with a missing, unknown or revoked key, or a key whose business is inactive, fails with `401 invalid_api_key`. It is never treated as anonymous.

## Scopes

Scopes have the form `<resource>:<read|write>`. Each operation in the [API reference](https://docs.panoflow.io/api-reference/accounts/list-accounts.md) needs one scope. A key or token without it gets `403 scope_missing`, with the scope it needs in `details.required_scope`.

| Scope | Covers |
| - | - |
| `business:read` | The business profile |
| `accounts:read`, `accounts:write` | Accounts, balances, statements and the transactions view |
| `recipients:read`, `recipients:write` | Banks, name enquiry and recipients |
| `transfers:read`, `transfers:write` | Transfers, batches, scheduled payments and payment limits |
| `approvals:read` | Approval status |
| `collections:read`, `collections:write` | Invoices, payment links, static virtual accounts and inbound credits |
| `payroll:read`, `payroll:write` | People, deductions, pay runs, payroll settings and payslips |
| `webhooks:read`, `webhooks:write` | Webhook endpoints, deliveries and events |

Give each key only the scopes its job needs.

## OAuth 2.1 for apps and agents

Apps and AI agents that act for a business use OAuth 2.1 with PKCE instead of API keys. A person in the business approves the app in the PanoFlow web app, and the app receives tokens limited to the scopes granted.

| Endpoint | URL |
| - | - |
| Authorization server metadata (RFC 8414) | `https://api.panoflow.io/.well-known/oauth-authorization-server` |
| Dynamic client registration (RFC 7591) | `POST https://api.panoflow.io/v1/oauth/register` |
| Authorization | `https://app.panoflow.io/oauth/authorize` |
| Token and refresh | `POST https://api.panoflow.io/v1/oauth/token` |
| Revocation (RFC 7009) | `POST https://api.panoflow.io/v1/oauth/revoke` |

* Registering a client grants nothing. A person must still approve it.
* The token endpoint serves public clients with PKCE and takes `application/x-www-form-urlencoded` bodies. Use `authorization_code` to exchange the code from the consent redirect and `refresh_token` to refresh.
* Access tokens live 15 minutes (`expires_in: 900`). Refresh tokens rotate on every use; reusing an old refresh token revokes the whole grant.
* An expired access token gets `401 token_expired`. Refresh it and retry.
* Revoking an access token ends that token. Revoking a refresh token revokes the whole grant.

Token endpoint errors use the RFC 6749 error shape, not the PanoFlow error shape. For example, a revoked or expired grant, a paused agent, or a reused refresh token returns `invalid_grant`.

For AI agents connecting through the PanoFlow MCP server, the scopes an agent can hold and its token lifetimes are on [Agents and MCP](https://docs.panoflow.io/agents-and-mcp.md).

## Operations you can't call with a key or token

Some parts of PanoFlow need a signed-in person in the web app and are not in this reference: sign-in and two-factor authentication, team and role management, API key management, agent setup, and deciding approvals. See [Approvals](https://docs.panoflow.io/approvals.md) for what that means for payments you create through the API.


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