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
- As a team Administrator on Unlimited, open Team > API keys.
- Enter a name, choose Permissions, and select Project access. Prefer one project over All projects.
- 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
| Scope | Allows |
|---|---|
projects_read | List projects and read project settings |
projects_create | Create projects within the plan limit |
projects_update | Change project settings, including security |
projects_delete | Permanently delete projects and their feedback |
feedback_read | List and read feedback |
feedback_create | Submit feedback when a key is required |
feedback_update | Archive or restore feedback, subject to the plan |
feedback_delete | Permanently delete feedback |
analytics_read | Read analytics on eligible plans |
integrations_read | Read integration settings without credentials |
integrations_create | Configure integrations on eligible plans |
integrations_update | Change integration settings and credentials |
integrations_delete | Remove 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.
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.