REST API authentication
Authenticate AbuseZero REST API requests: credential types, workspace selection, scopes and permissions.
Every request to the AbuseZero REST API carries one credential. The credential decides which workspace the request reaches and what it may do there. A credential can never reach a workspace it wasn't granted, and no request parameter can widen its access.
Credential types
| Credential | Format | Use it in | Access |
|---|---|---|---|
| Secret key (full access) | sk_… | Your server | Every server scope in one workspace. |
| Restricted key | rk_… | Your server | Only the scopes chosen for it, in one workspace. Its scopes can be changed later. |
| Publishable key | pk_… | The browser SDK and standalone browser script | Browser data collection only. Safe to ship in browser code. |
| OAuth access token | Opaque token | The AbuseZero CLI, MCP clients and OAuth apps | The scopes the user approved, in the workspaces they can access. |
Create and manage keys in the dashboard under Developers. A key's type and expiry never change after it's created. An expired or revoked key stops working at once.
Keep secret and restricted keys on your server. Never put them in browser code, mobile apps, URLs or logs. Use a restricted key with only the scopes a service needs.
Send a credential
Send the credential as a bearer token in the Authorization header.
curl https://api.abusezero.com/v1/benefits \
-H "Authorization: Bearer $ABUSEZERO_SECRET_KEY"Choose a workspace
An API key belongs to exactly one workspace, so requests made with it need no workspace header.
An OAuth access token reaches the workspaces it was granted: only that workspace when it was granted for one workspace, otherwise every workspace its user can access. Every request made with one chooses the workspace in the AbuseZero-Workspace header, using the workspace's ws_ ID. List the available workspaces with GET /v1/workspaces, the one endpoint that works without the header.
const abusezero = new AbuseZero({
accessToken: process.env.ABUSEZERO_ACCESS_TOKEN!,
workspace: "ws_6d2a8f14-3c9e-4b71-a5d0-8e2f6c4a9b13",
outage: "throw",
});The AbuseZero CLI and the AbuseZero MCP server handle OAuth sign-in and workspace selection for you. See AbuseZero CLI and AbuseZero MCP server.
Scopes
Each endpoint requires one scope. Secret keys hold every server scope. Restricted keys and OAuth access tokens hold only the scopes granted to them.
| Scope | Allows |
|---|---|
workspaces:read | List the workspaces the credential can use. |
evaluations:create | Evaluate claims with POST /v1/evaluations. |
evaluations:read | List and read evaluations, and read their association graphs. |
evaluation_evidence:read | Read the retained request details of an evaluation. Also needed, together with the export scopes, to create or download exports that include them. |
outcomes:read | List and read outcomes. |
outcomes:write | Report outcomes. |
simulations:run | Run previews, simulations and replays. |
benefits:read | List and read benefits. |
benefits:write | Create, update and delete benefits. |
policies:read | List and read policies, policy versions and the conditions available to custom rules. |
policies:write | Create, update, duplicate and delete custom policies. |
access_lists:read | List and read allow and block list entries. |
access_lists:write | Add and delete allow and block list entries. |
custom_identifiers:read | List and read custom identifiers. |
custom_identifiers:write | Register and delete custom identifiers. |
imports:read | List and read imports and their error reports. |
imports:write | Create, validate, confirm and cancel imports. |
exports:read | List and read exports, and download finished ones. |
exports:create | Request exports. |
data_deletions:read | List and read data deletions. |
data_deletions:write | Preview and request data deletions. |
analytics:read | Read daily evaluation totals. |
request_logs:read | List and read request logs. |
audit_logs:read | List and read audit events. |
browser_collection:read | Read browser setup: your site list and recent browser data coverage. |
browser_collection:write | Update your site list. |
agents:read | List the AI agents AbuseZero recognizes. |
observations:create | Send browser data. Publishable keys only; the browser SDK uses it for you. |
A request without the required scope returns KEY_PERMISSION_DENIED for API keys and OAUTH_SCOPE_REQUIRED for OAuth access tokens.
Member permissions for OAuth
An OAuth access token acts for a person, so some scopes also need that person to hold a permission in the workspace. Workspace owners hold every permission, and admins also hold Manage integrations, lists, and imports. Owners grant permissions to other members in the dashboard.
| Scope | Permission the member needs |
|---|---|
evaluation_evidence:read | Reveal personal identifiers |
exports:create | Export data |
data_deletions:read, data_deletions:write | Delete matching history |
audit_logs:read | Manage integrations, lists, and imports |
benefits:write, policies:write | Publish policies and benefits |
Without the permission, the request returns PERMISSION_REQUIRED. API keys don't need member permissions; their scopes decide their access.
Errors
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | AUTHENTICATION_REQUIRED | The request has no credential. | Send Authorization: Bearer with a key or access token. |
| 401 | INVALID_API_KEY | The key is unknown or revoked. | Create a new key in Developers. |
| 401 | API_KEY_EXPIRED | The key passed its expiry. | Create a new key in Developers and replace the old one. |
| 401 | INVALID_ACCESS_TOKEN | The OAuth access token is invalid or expired. A value that isn't a complete API key is read as an access token. | Sign in again, then retry. If you meant to send an API key, check that it was copied in full. |
| 403 | KEY_TYPE_NOT_ALLOWED | A publishable key was used on a server endpoint, or a server key in the browser. | Use a secret or restricted key on your server, and the publishable key in the browser. |
| 403 | KEY_PERMISSION_DENIED | The API key lacks the endpoint's scope. | Use a key with the scope named in the message. |
| 403 | OAUTH_SCOPE_REQUIRED | The access token lacks the endpoint's scope. | Authorize the scope named in the message, then retry. |
| 403 | WORKSPACE_REQUIRED | An OAuth request has no valid AbuseZero-Workspace header. | Send a ws_ ID from GET /v1/workspaces. |
| 403 | WORKSPACE_ACCESS_DENIED | The credential can't reach that workspace. | Choose a workspace the credential belongs to. |
| 403 | PERMISSION_REQUIRED | The signed-in member lacks a permission the scope needs. | Ask the workspace owner for the permission. |
| 403 | EVIDENCE_SCOPE_REQUIRED | An export with evidence needs evaluation_evidence:read. | Add the scope, or request the export without evidence. |
| 403 | ONBOARDING_REQUIRED | The workspace hasn't finished setup. | Ask the workspace owner to finish onboarding in the dashboard. |
See REST API errors for the full list.
How is this guide?
Last updated on