Skip to content
poacher.

Developers · API 1.10.1

Sign-in and permissions

Developer docsSign-in and permissions
  1. Overview
  2. Quickstart
  3. Connect over MCP
  4. MCP tools
  5. REST API
  6. Sign-in and permissions
  7. Workflows
  8. Errors
  9. Changelog

Scoped API keys, OAuth 2.1 for MCP clients, every permission and how a client asks for more.

Every key and token belongs to one Poacher account, carries only the permissions the person ticked and expires after 7, 30 or 90 days. The person can see and revoke each one in Developer access.

PermissionAllowsOn the consent screen
account:readRead balances, monthly cap and billing environment.Ticked
alerts:readRead alerts and their saved settings.Ticked
results:readRead matching results.Ticked
alerts:writeRename and pause alerts.Unticked: the person must choose it
work:executeQuote and run approved paid previews and one-off checks.Unticked: the person must choose it
channels:manageAdd and confirm channels; choose where an alert sends results.Unticked: the person must choose it

A key never includes another customer’s data or administrator access. Billing settings cannot be changed through the API.

Create a key in Developer access and send it as Authorization: Bearer poacher_v1_…. Creating or revoking a key needs a sign-in from the last ten minutes. An account can have ten active keys.

MCP clients sign in with OAuth 2.1, so nobody pastes a key. The access token is an ordinary scoped Poacher key.

Protected resource
https://app.poacher.io/mcp (metadata)
Authorization server
https://app.poacher.io (metadata)
Grant
authorization code with PKCE (S256); public clients only
Client registration
client ID metadata documents, or dynamic registration at /api/oauth/register
Tokens
7, 30 or 90 days, chosen by the person; no refresh tokens
  1. The client calls a tool and gets HTTP 401 with WWW-Authenticate: Bearer resource_metadata="…", scope="…".
  2. It reads the protected-resource and authorization-server metadata, then sends the person to /oauth/authorize.
  3. The person signs in, sees which app is asking and where it will return, and ticks the permissions to allow. Writes and spending start unticked.
  4. Poacher redirects back with a code and iss; the client exchanges the code at /api/oauth/token.

Redirect addresses must be HTTPS, loopback HTTP (http://127.0.0.1 or http://localhost, any port) or an app’s own scheme such as cursor://. Connecting the same app again replaces its earlier key. Replaying a code revokes the key it produced.

When a signed-in client calls a tool its token cannot use, /mcp answers HTTP 403:

HTTP header
WWW-Authenticate: Bearer resource_metadata="https://app.poacher.io/.well-known/oauth-protected-resource/mcp", error="insufficient_scope", scope="alerts:read results:read"

scope lists everything the client should ask for: what it has and what it needs. The REST API answers the same way with required_scope in the error body.

View this page as MarkdownAPI version 1.10.1Changelog