Authentication & scopes
How API keys, bearer tokens, scopes, and project restrictions work.
View as MarkdownEvery request to an authenticated aclipp public API endpoint needs an API key. OAuth access tokens authenticate MCP connections; see Connect AI agents with MCP for that workflow. The credential identifies the workspace, the principal, and exactly what the request is allowed to do.
API keys
Create and revoke keys in workspace settings. A key looks like aclipp_live_... and is shown in full only once, at creation. Send it as a bearer token on every request:
The workspace is implied by the key, so it never appears in the URL. Revoking a key takes effect within about a minute.
OAuth access tokens
OAuth access tokens authenticate MCP connections, not public API requests. Registered OAuth clients receive an access token after you approve the connection in the browser. The client sends that token in the same bearer header and manages it for you:
An OAuth access token carries the scopes and optional project restriction granted to that MCP connection.
Scopes
Every credential is granted a set of scopes and can only do what they allow. Scopes follow a resource:action pattern:
:readgrants read access to a resource.:writeallows creating, updating, and deleting.
| Scope | Grants |
|---|---|
projects:read / projects:write | Read / manage projects |
prompts:read / prompts:write | Read / manage AI visibility prompts and prompt topics |
clippings:read / clippings:write | Read / manage clippings |
outlets:read / outlets:write | Read / manage the workspace outlet catalog |
authors:read / authors:write | Read authors; write access is reserved for author mutations |
reports:read / reports:write | Read / manage reports |
dashboards:read / dashboards:write | Read / manage dashboards |
analytics:read | Read the analytics catalog and query aggregate analytics |
ai-visibility:read | Read AI visibility chats, source domains, and source URLs |
Grant a credential only the scopes it needs. A reporting script, for example, might get reports:read and nothing else. A request missing a required scope is rejected with 403 FORBIDDEN.
Project restrictions
An API key or OAuth connection can optionally be restricted to specific projects. A restricted credential can only read or write project-owned resources within its project set; anything outside it is treated as not found.
Outlets are workspace-owned rather than project-owned. A project-restricted credential must provide one of its allowed project IDs when reading outlets. The outlet catalog remains workspace-wide, while clippingsCount is calculated only for that project. Outlet mutations require an unrestricted credential.
Errors
Authentication and authorization failures use the standard error shape:
401— missing, invalid, expired, or revoked credential.403— the credential is valid but lacks the required scope.404— the resource doesn't exist, or it's outside the credential's project scope.
See the API reference for the required scope on each endpoint.