Skip to documentation

API authentication and credential types

Choose organization keys, personal keys or OAuth, with the correct headers and endpoint permissions.

Updated Read as Markdown

Choose a credential for the job

Use https://api.pollenate.dev as the REST API base URL. Send JSON with Content-Type: application/json; use endpoint paths without a trailing slash to avoid a redirect.

Credential Acts as Where to create it Header
Organization API key, pk_live_… The organization, within its scopes and optional brand restriction Settings → API Keys X-Pollenate-Key: … for REST
Personal API key, pk_user_… Its owner, within current membership, role and brand access Profile → Personal API Keys X-Pollenate-Key: … on supported REST routes
OAuth access token, pol_at_… The person who approved the client The client's Pollenate sign-in and consent flow Authorization: Bearer …
Browser session The signed-in person Pollenate login Managed by the app

MCP accepts an API key or OAuth token in Authorization: Bearer …; it also accepts X-Pollenate-Key. Do not assume the MCP header rules apply to every REST endpoint.

Endpoint compatibility

Endpoint family Organization key Personal key OAuth
POST /collect Yes, collect, write or admin No No
/organizations/:orgId/inboxes, feedback, search Organization-wide key; route scopes apply No MCP sign-ins are not supported here
/organizations/:orgId/feedback-pages Organization-wide key; route scopes apply Yes, within the owner's permissions Yes, within granted scopes and role
/v1/organizations/:orgId/feedback-pages Yes; brand restrictions are supported No Yes; route scopes and visibility apply
/zapier Yes No No
/mcp Yes Yes Yes

Personal keys and MCP sign-ins have an explicit REST allowlist: organization list/detail, brands list and feedback-page routes. Use MCP's tools for user-scoped inbox and feedback access. An organization key scoped to a brand is rejected by the organization-level management routes; use a key without a brand restriction for those examples.

Organization scopes

  • collect: submit feedback; appropriate for a browser widget.
  • list: read form structure through the published-form API, not customer responses.
  • read: read feedback, analytics and supported metadata.
  • write: create and update supported resources. It does not grant every read or destructive operation.
  • admin: broad administrative access. Only an organization owner can create a key with this scope.

Treat an embedded collect key as visible to visitors. Keep read, write, admin, personal keys and OAuth tokens on trusted servers or in the client's credential storage. Avoid placing them in URLs or committed examples.

A key is shown in full when created. Save it then, choose an expiry where appropriate, and revoke it when no longer needed. Personal keys support collect, list, read and write, with at most 20 active keys per person per organization. They cannot grant more access than their owner.

Verify access

bash
curl https://api.pollenate.dev/organizations/ORG_ID/inboxes \
  -H "X-Pollenate-Key: $POLLENATE_READ_KEY"

Use an organization-wide key with read. A 401 means the credential is missing, invalid, expired or revoked. A 403 usually means the credential is valid but the scope, organization, brand or role does not allow that route. Copying an inbox ID from another organization does not grant access.

OAuth client integration

OAuth clients should use discovery and consent, not a copied browser session.

Endpoint Purpose
GET https://api.pollenate.dev/.well-known/oauth-protected-resource Discover the resource and authorization server
GET https://api.pollenate.dev/.well-known/oauth-authorization-server Discover authorization, token, registration and revocation endpoints
https://pollenate.dev/oauth/authorize Browser-facing consent screen
POST https://api.pollenate.dev/oauth/token Exchange an authorization code or refresh token
POST https://api.pollenate.dev/oauth/revoke Revoke a token

Remote MCP clients can register through POST /oauth/register. Dynamically registered clients are public clients without a client secret; they must use PKCE S256. Follow the discovered metadata rather than inventing a password or client-secret grant. Registered redirect URIs, requested scopes and the MCP resource https://api.pollenate.dev/mcp must match the authorization flow.

Access tokens expire after one hour. Refresh tokens have a 90-day lifetime and rotate on use; save the new token pair and stop using the previous refresh token. Revoking or disconnecting a grant removes access. Tokens issued for the MCP resource are not interchangeable with credentials for an arbitrary service.

See MCP setup for normal client configuration and MCP permissions for the scope and ownership rules.