Produktly API authentication

How to authenticate against the Produktly REST API and MCP server with an API key, including scopes, rate limits, and error codes.

The Produktly REST API and the MCP server authenticate the same way: an API key sent as a Bearer token. One key works for both.

REST base URL: https://api.produktly.com/api/v1
MCP endpoint: https://api.produktly.com/api/mcp
OpenAPI spec: https://produktly.com/docs/openapi.json (no auth required)
Full endpoint list: API reference

Get an API key

Sign in to Produktly and open Settings → API keys.
Give the key a name (for example Production, MCP, or CI) and select Generate new private key.
Copy the key. It is shown in full in the list, so you can come back for it, but treat it like a password.

Keys belong to a company, not to a user, so a key keeps working after the person who created it leaves.

Send the key

Put the key in an Authorization: Bearer header on every request:

curl https://api.produktly.com/api/v1/changelogs \
  -H "Authorization: Bearer <your-api-key>"

The one exception is GET /api/v1/openapi.json, which is public and needs no header.

An MCP client sends the same header, set in its server config:

"headers": {
  "Authorization": "Bearer <your-api-key>"
}

The MCP server docs have the full config for Claude Code, Cursor, Windsurf, and VS Code.

Which key is which

Produktly has three different tokens and they are easy to mix up:

Token	Where it lives	Secret?	Used for
API key (private key)	Settings → API keys	Yes, server-side only	REST API, MCP server, signing identity verification hashes
Client Auth Token	Your install snippet	No, public by design	Identifying your account to the widget script in the browser
Identity verification hash	Generated per user on your backend	Derived from an API key	Proving a `identifyUser` call is genuine — see Identity verification

Only the first one authenticates API and MCP requests. Never ship an API key to the browser: anyone holding it can read and write all of your Produktly data.

Scopes

Every key carries a set of scopes:

Scope	Grants
`read`	All `GET` requests
`write`	Everything else — create, update, delete
`publish`	Publishing a widget, and editing one that is already live

Requests are checked against the scopes on the key: GET needs read, any other method needs write, and publish is enforced inside the individual endpoints.

Keys generated in the dashboard today carry all three scopes. Scoped-down keys can be created through the dashboard API by passing a scopes array, which is what an agent integration would use to get a key that can draft widgets but not publish them.

Errors

Authentication and quota problems come back in the standard error envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

Status	Code	Meaning
401	`unauthorized`	No `Authorization: Bearer` header, or the key is invalid or has been deleted
403	`insufficient_scope`	Valid key, but it lacks the scope the endpoint needs
409	`widget_is_live`	The widget is published and the key has no `publish` scope. Unpublish it in the dashboard, or use a key that can publish
429	`rate_limit_exceeded`	Over the rate limit — see below

MCP clients get the same failures as JSON-RPC errors rather than this envelope.

Rate limits

Limits are per API key, not per IP:

60 requests per minute for most endpoints
300 requests per minute for /users, which has its own bucket so backend user syncs do not starve everything else

Every response carries the current state:

X-RateLimit-Limit — requests allowed in the window
X-RateLimit-Remaining — requests left
X-RateLimit-Reset — Unix seconds when the bucket refills

A 429 also sets Retry-After in seconds. Back off for that long and retry.

Rotating and revoking

Delete a key from Settings → API keys to revoke it immediately. There is no grace period, so generate the replacement and roll it out before deleting the old one.

If a key leaks, delete it first and investigate second. A leaked key can read and modify every widget, response, and identified user in the account.