Skip to main content
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:
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 needs one scope. A key or token without it gets 403 scope_missing, with the scope it needs in details.required_scope. 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.
  • 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.

​
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 for what that means for payments you create through the API.