API keys

An API key is a secret string that proves to Zoop who is making a request. Unlike the browser-based OAuth flow, there is no redirect or login screen — you attach the key directly to each request, and Zoop lets it through. Use API keys in server-side scripts, background jobs, or automated pipelines that run without a human present.

Two key types

Zoop issues two kinds of API key. You can tell them apart by their prefix — the short tag at the start of the key string:

User keys tie every write to a specific team member. Any API tool that records created_by or updated_by, or that otherwise requires a real user identity, needs a user key. Use a user key when your integration writes data on behalf of a specific person — for example, a job-creation script that should record which technician submitted the work.

Tenant keys are for read-heavy integrations or pipelines where individual attribution does not matter — for example, a reporting dashboard that reads invoices and jobs. They cannot call tools that require a user identity.

Create a key

The key is active immediately after creation.

Send a request

To make an authenticated request, add your key to the Authorization header using the Bearer scheme — that just means the word Bearer, a space, then your key. You do this on every request; there is no separate login step first.

curl -X POST https://app.zoop.example/api/mcp \
  -H "Authorization: Bearer zoop_uk_<your-secret>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"customers.search","arguments":{"q":"Henderson"}}}'

const response = await fetch('https://app.zoop.example/api/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZOOP_API_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'customers.search',
      arguments: { q: 'Henderson' },
    },
  }),
})

On every request, Zoop hashes the token and looks it up in the database. There is no session or cache — the lookup happens on every single call.

Scopes

Scopes are permissions. Each scope unlocks a set of API tools, and a key can only call tools covered by the scopes it was issued with. Scopes are fixed at creation — you cannot add scopes to an existing key. If you need more scopes later, revoke the key and create a new one with the broader set.

See scopes for the full scope catalog.

Key expiry

Keys do not expire by default. You can set an expiry date when you create a key — once that date passes, the key stops working and returns a 401 error with error: "expired". Set an expiry if you want automatic cleanup for short-lived integrations.

Revoke a key

Go to Settings → API & MCP, find the key in the list, and select Revoke. Revocation is instant — the key stops working on the very next request. There is no grace period, so make sure any running integrations that use it are updated first, or expect them to start returning 401 errors immediately.

Rotate a key

Key rotation means replacing an old key with a new one without downtime. Do this on a schedule, or whenever a key may have been exposed.

Error reference

If a request fails authentication or authorization, Zoop returns one of these responses:

If you receive 401 with reason: "key_revoked", the key is permanently dead and retrying will not help. Stop the integration and issue a new key before restarting it.

Security checklist

• Store the key in an environment variable or a secrets manager. Never put it in source code or commit it to version control.
• Request only the scopes your integration actually needs. Fewer scopes means less damage if the key leaks.
• Use one key per integration. That way, if one key is compromised, you revoke only that key without affecting anything else.
• If you think a key has been exposed, revoke it now — revocation takes effect on the next request, not at the next rotation cycle.

Related

• Scopes — full list of available scopes
• OAuth — user-delegated access via browser flow
• Errors — full error code reference
• Rate limits — per-credential and per-tenant limits