Authentication & scopes
The Skoup API authenticates requests with API keys sent as a Bearer token:
curl https://api.skoup.ai/v1/brands \
-H "Authorization: Bearer skoup_live_9xQw…8f2a"Requests without a key, or with an unknown or revoked key, fail with 401
(authentication_required,
invalid_api_key,
api_key_revoked). All calls must be made over HTTPS.
API keys
Keys are created by the owners of a workspace in Settings → Developers → API keys.
| Prefix | Mode | Data |
|---|---|---|
skoup_live_ | Live | Your workspace — real brands, real measurements. |
skoup_test_ | Test | A shared demo workspace. Writes are validated but never saved. See Test mode. |
A key belongs to a workspace, not to a person: it keeps working when the colleague who created it leaves. The interface shows who created each key, when, and when it was last used.
Treat keys like passwords. Never ship them in a browser, a mobile app or a public repository.
If a key leaks, revoke it: calls made with it fail with 401 immediately.
Scopes
Each key carries a list of scopes. A request outside them fails with 403
insufficient_scope. Give each integration the smallest set it
needs — a reporting dashboard only needs *:read scopes.
| Scope | Grants |
|---|---|
brands:read | List brands and their markets. |
metrics:read | Visibility metrics, queries, samplings, competitors, readiness. |
alerts:read | List and retrieve alerts. |
alerts:write | Mark alerts treated, dismiss them, trigger a verification. |
tasks:read | List and retrieve tasks. |
tasks:write | Create and update tasks, move them across the board. |
queries:read | List the tracked queries (prompts). |
queries:write | Add queries, enable or disable them. |
products:read | List and retrieve products. |
products:write | Create and update manual products. |
revenue:read | AI-attributed orders and revenue. |
events:read | List and retrieve events. |
webhooks:write | Manage webhook endpoints through the API. |
Brand restrictions
A key gives access to every brand of the workspace by default. Agencies usually restrict a key
to a single client’s brand: the key then behaves as if the other brands did not exist — they are
absent from GET /v1/brands and return 404
resource_missing when addressed directly.
Who acted?
Writes made with a key are recorded as made by that key. Skoup’s activity log shows the key name, so a task created by your ticketing integration can be told apart from a task created by a teammate.
AI assistants (MCP)
The MCP server accepts the same keys, or a personal OAuth connection from Claude or ChatGPT, which carries the rights of the signed-in person.