API keys

The Pliic REST API is authenticated with secret keys (sk_live_…), one per app. Each key carries a set of scopes that limit what it can access.

The API is available on the Starter and Pro plans. The Free plan does not include this feature.

Where to manage

Go to Settings → API keys. The page lists each app in your team with its secret key, the current scopes, last usage, and status (active or revoked).

Only members with the Admin or Owner role can view and manage API keys.

Scopes

Scopes define which parts of the API the key can use:

Scope	Allows
suggestions:read	Read suggestions
suggestions:write	Create and update suggestions
tickets:read	Read support tickets
tickets:write	Create and update tickets
analytics:read	Read analytics data
privacy:read	Export user privacy data
privacy:write	Delete user privacy data

Select Full access to grant every current and future scope.

Every new key starts read-only

When an app is created, its secret key carries suggestions:read and tickets:read and nothing else. That is deliberate: a key only gains write permission when someone grants it. So your integration’s first write request (POST /api/v1/suggestions, POST /api/v1/tickets) fails until you tick the write scope here.

Insufficient scope error

When the key is valid but lacks the scope an endpoint requires, the response is a 403 with this body:

{
    "message": "This API key is not allowed to perform this request: it is missing the \"tickets:write\" scope. …",
    "error": "insufficient_scope",
    "required_scope": "tickets:write",
    "granted_scopes": ["suggestions:read", "tickets:read"],
    "manage_scopes_url": "https://pliic.com/team/your-team/settings/api-keys",
    "docs_url": "https://docs.pliic.com/integrations/api-keys/"
}

• error is a stable code: branch on it, not on the message text.
• required_scope is what is missing, granted_scopes is what the key has today.
• manage_scopes_url opens this screen directly so you can enable the scope.

The error body never contains the key or its hash.

Rotating a key

Under Key actions → Rotate key, a new secret key is generated and shown only once. Scopes are preserved, but the old key stops working immediately. Update your integrations with the new value before dismissing the notice.

Revoke and restore

Revoke disables the key immediately — every request then returns 401. Use Restore to re-enable it. The secret key itself does not change when revoking or restoring.

API reference

The API reference button opens the interactive documentation (OpenAPI) with every endpoint, parameter, and example. The specification is also publicly available at /api/v1/openapi.json.