For the complete documentation index, see llms.txt
Skip to main content

API key security

Use team API keys to authenticate REST API and MCP clients. Give each key only the permissions and projects its client needs.

How keys work​

  1. As a team Administrator on Unlimited, open Team > API keys.
  2. Enter a name, choose Permissions, and select Project access. Prefer one project over All projects.
  3. Click Create API key and copy the full key. It is shown once.

Use Revoke beside a key to stop its access immediately. To rotate a key, create a replacement, update the client, and revoke the old key after verifying the replacement.

Existing keys remain valid after a downgrade, subject to current project and feature access. Official integrations such as WordPress can provision their own key on any plan.

Scoped permissions​

ScopeAllows
projects_readList projects and read project settings
projects_createCreate projects within the plan limit
projects_updateChange project settings, including security
projects_deletePermanently delete projects and their feedback
feedback_readList and read feedback
feedback_createSubmit feedback when a key is required
feedback_updateArchive or restore feedback, subject to the plan
feedback_deletePermanently delete feedback
analytics_readRead analytics on eligible plans
integrations_readRead integration settings without credentials
integrations_createConfigure integrations on eligible plans
integrations_updateChange integration settings and credentials
integrations_deleteRemove integrations

A reporting client usually needs only feedback_read. A client that updates the site URL needs projects_update. Grant delete permissions only if deletion is part of the workflow.

Older names remain accepted: feedback:read maps to feedback_read, feedback:submit and feedback_submit map to feedback_create, and project:manage grants projects_read and projects_update.

A valid key with a missing scope returns 403. A project outside the key's team or project restriction returns 404. Team-wide endpoints reject project-restricted keys.

Requiring a key for submissions​

By default, visitors can submit feedback without a key. To require one, open Projects > your project > Settings > Security, select Require an API key for submissions, and click Save on that card.

For the installed widget, use a project-restricted key with only feedback_create. Set the widget's api-key attribute:

<feedback-button project="YOUR_PROJECT_ID" api-key="YOUR_SUBMISSION_KEY">Feedback</feedback-button>

Replace YOUR_PROJECT_ID with the ID from Snippet and YOUR_SUBMISSION_KEY with the key you created. Missing or invalid keys return 401. A key without the submit permission returns 403.

Keys in a page are visible to visitors

Anyone who can load the page can extract its key. Never put a key with read, update, or delete permissions in browser code. For private credentials, submit through your backend instead.

A custom API v2 client also needs projects_read if it fetches a protected project's configuration. That permission exposes project settings. Keep that key on your server. See protected configuration in v2.

MCP connections​

Prefer OAuth for MCP to authorize an assistant without sharing an API key. Choose a team, project coverage, and permissions in PushFeedback. Revoke the connection under Team > Connected apps.

For clients without OAuth, configure an Authorization: Api-Key HTTP header in the client's secret settings. Choose scopes and project coverage when creating the key. An All projects key is only needed for team-wide operations.

The single /v2/mcp?api_key=... endpoint accepts both project-restricted and All projects keys. Project-specific MCP URLs are no longer supported. The MCP server derives project access and available tools from the key. Treat those URLs as secrets and prefer a secret header for new manual connections. Never publish management or feedback-reading keys in the widget or commit them to version control.

Handling keys safely​

Store private keys in environment variables or a secrets manager. Keep them out of source control, browser code, screenshots, shared URLs, and logs. Send REST API keys over HTTPS in the Authorization: Api-Key YOUR_API_KEY header.

See the API authentication reference for examples and MCP setup for client connections.