API authentication and credential types
Choose organization keys, personal keys or OAuth, with the correct headers and endpoint permissions.
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
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.