Workspaces

A workspace holds your benefits, policies, allow and block lists, claim history and credentials. Each workspace's data stays in that workspace. Keys, OAuth tokens and AbuseZero MCP server sessions reach only the workspaces they were granted.

Workspace IDs start with ws_.

How requests choose a workspaceCopy Anchor Link

• API keys belong to one workspace. See secret and restricted keys. Every request made with a key acts on that workspace.
• OAuth tokens act for the signed-in person and reach only the workspaces they were granted. Every request made with a token, except listing workspaces, names its workspace in the AbuseZero-Workspace header.

curl https://api.abusezero.com/v1/benefits \
  -H "Authorization: Bearer $ABUSEZERO_ACCESS_TOKEN" \
  -H "AbuseZero-Workspace: ws_3a9c1e5b-7d2f-4b8a-a6e0-2c4f8b1d9e57"

The AbuseZero Node.js SDK sends the header for you when you pass workspace:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({
  accessToken: process.env.ABUSEZERO_ACCESS_TOKEN!,
  workspace: "ws_3a9c1e5b-7d2f-4b8a-a6e0-2c4f8b1d9e57",
  outage: "throw",
});

The AbuseZero CLI chooses its workspace with abusezero workspaces use ws_…. See AbuseZero CLI.

The workspace objectCopy Anchor Link

{
  "object": "workspace",
  "id": "ws_3a9c1e5b-7d2f-4b8a-a6e0-2c4f8b1d9e57",
  "name": "Acme Analytics"
}

List workspacesCopy Anchor Link

With an API key, returns the key's own workspace. With an OAuth token granted for one workspace, returns only that workspace. With any other OAuth token, returns every workspace the signed-in person belongs to. This request doesn't need the AbuseZero-Workspace header.

Also available as abusezero workspaces list in the AbuseZero CLI, abusezero_list_workspaces on the AbuseZero MCP server and workspaces() in the AbuseZero Node.js SDK.

ExampleCopy Anchor Link

const workspaces = await abusezero.workspaces();

ResponseCopy Anchor Link

Returns 200. Every workspace comes back in one response, so next_cursor is always null.

{
  "object": "list",
  "data": [
    {
      "object": "workspace",
      "id": "ws_3a9c1e5b-7d2f-4b8a-a6e0-2c4f8b1d9e57",
      "name": "Acme Analytics"
    },
    {
      "object": "workspace",
      "id": "ws_9e1b5d3f-2a7c-4e6b-8f0d-4a2c6e8b0d13",
      "name": "Acme Labs"
    }
  ],
  "next_cursor": null
}

Workspace errorsCopy Anchor Link

These errors can come back from any request made with an OAuth token.

For every other code, see REST API errors.

RelatedCopy Anchor Link