AbuseZeroAbuseZero

API keys

List, create, change, roll and revoke your workspace's API keys, and show a replacement key, with the AbuseZero REST API.

An API key belongs to one workspace and authenticates your server's requests. Listing keys needs operations:general. Creating, changing, rolling and revoking them needs operations:management, which no API key holds, so those calls use an OAuth sign-in, such as the AbuseZero CLI, or a machine client. The same keys appear in Developers → API & Webhooks → API keys.

Examples on this page that change keys use an OAuth access token:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({
  accessToken: process.env.ABUSEZERO_ACCESS_TOKEN!,
  workspace: "59670872302871291997",
  outage: "throw",
});

The API key object

{
  "object": "api_key",
  "id": "73492810562018437529",
  "name": "Production server",
  "type": "restricted",
  "scopes": ["operations:general"],
  "prefix": "rk_",
  "last_four": "x7Qa",
  "value": null,
  "status": "active",
  "replacement_available": false,
  "expires_at": "2027-11-10T09:00:00.000Z",
  "last_used_at": "2026-11-10T12:30:00.000Z",
  "created_at": "2026-11-10T09:00:00.000Z"
}
FieldTypeDescription
object"api_key"The object type.
idstringThe key's ID. Request logs name it as api_key.
namestringThe key's name.
typesecret, restricted or publishableA secret key holds operations:general and operations:configuration. A restricted key holds only the scopes chosen for it. The workspace's one publishable key is for the AbuseZero browser SDK.
scopesarray of stringsThe scopes the key holds.
prefixstring or nullThe start of the key: sk_, rk_ or pk_.
last_fourstring or nullThe key's last four characters, to tell keys apart.
valuestring or nullThe publishable key's full value, which is safe in page source. null for every other key.
statusactive, expired or revokedWhether the key still works.
replacement_availablebooleanWhether AbuseZero replaced this key for you and its value can be shown once.
expires_atstring or nullWhen the key stops working. null means it never expires.
last_used_atstring or nullWhen the key last made a request, within a minute.
created_atstringWhen the key was created.

A secret or restricted key's full value is returned once, as secret, in the response that creates or rolls it. Nobody can read it again, including support.

List API keys

Returns the workspace's keys, newest first, including revoked and expired ones.

MethodPathScopeIdempotency-Key
GET/v1/api-keysoperations:generalNot used

Also available as abusezero api-keys list in the AbuseZero CLI, abusezero_list_api_keys on the AbuseZero MCP server and apiKeys() in the AbuseZero Node.js SDK.

Query parameters

ParameterTypeRequiredLimitsDescription
limitintegerNo1 to 100, default 50How many keys to return.
cursorstringNoThe next_cursor from the previous page, unchanged.

Example

const keys = await abusezero.apiKeys();

Response

Returns 200 with a list of API key objects.

Create an API key

Creates a secret or restricted key and returns its full value once, in secret. Store it in your secret store straight away.

MethodPathScopeIdempotency-Key
POST/v1/api-keysoperations:managementRequired

Also available as abusezero api-keys create in the AbuseZero CLI, abusezero_create_api_key on the AbuseZero MCP server and createApiKey() in the AbuseZero Node.js SDK.

  • With an OAuth token, the signed-in member needs the Create and revoke keys permission, as in the dashboard.
  • A key can hold operations:general and operations:configuration, never operations:management.
  • The workspace owner and admins get the Key created email when a member or a machine client creates a key.
  • Sending the same request again with the same Idempotency-Key returns SECRET_ALREADY_SHOWN, because the secret is shown once. To get another key, send a new request with a new key.

Body parameters

ParameterTypeRequiredLimitsDescription
namestringYes1 to 80 charactersThe key's name.
typesecret or restrictedYesThe key's type. It never changes.
scopesarray of stringsFor restricted keysoperations:general, operations:configuration or bothThe scopes a restricted key holds. Leave it out for a secret key.
expires_in_daysinteger or nullNo1 to 3,650, default nullWhole days until the key expires. null means it never expires.

Example

const key = await abusezero.createApiKey(
  { name: "Production server", type: "restricted", scopes: ["operations:general"], expires_in_days: 365 },
  "create-production-key",
);
// key.secret holds the full key. Store it now: it isn't shown again.

Response

Returns 201 with the API key object and its secret.

{
  "object": "api_key",
  "id": "73492810562018437529",
  "name": "Production server",
  "type": "restricted",
  "scopes": ["operations:general"],
  "prefix": "rk_",
  "last_four": "x7Qa",
  "value": null,
  "status": "active",
  "replacement_available": false,
  "expires_at": "2027-11-10T09:00:00.000Z",
  "last_used_at": null,
  "created_at": "2026-11-10T09:00:00.000Z",
  "secret": "rk_73492810562018437529.…"
}

Errors

CodeStatusMeaning
KEY_PERMISSION_DENIED403The request used an API key. Use an OAuth sign-in or a machine client.
PERMISSION_REQUIRED403With an OAuth token, the signed-in member doesn't have Create and revoke keys.
KEY_SCOPE422scopes includes operations:management or observations:create.
SCOPE_REQUIRED422A restricted key needs at least one scope.
INVALID_EXPIRY422expires_in_days is outside 1 to 3,650.
SECRET_ALREADY_SHOWN409This request already created a key, and its secret isn't shown again.

Update an API key

Changes a key's name, a restricted key's scopes, or its expiry. A key's type never changes.

MethodPathScopeIdempotency-Key
PATCH/v1/api-keys/{id}operations:managementRequired

Also available as abusezero api-keys update in the AbuseZero CLI, abusezero_update_api_key on the AbuseZero MCP server and updateApiKey() in the AbuseZero Node.js SDK.

  • A new expiry counts from the moment it's saved, and the key's expiry emails start again for the new date.
  • A rolled key's end time can't change. Change its replacement instead.
  • A change to a restricted key's scopes emails the workspace owner and admins.

Body parameters

Send at least one.

ParameterTypeRequiredLimitsDescription
namestringNo1 to 80 charactersThe key's new name.
scopesarray of stringsNooperations:general, operations:configuration or bothA restricted key's new scopes.
expires_in_daysinteger or nullNo1 to 3,650Whole days from now until the key expires. null means it never expires.

Example

const key = await abusezero.updateApiKey("73492810562018437529", { name: "Production API server" }, "rename-production-key");

Response

Returns 200 with the API key object.

Errors

CodeStatusMeaning
KEY_NOT_FOUND404No key with this ID exists in the workspace.
KEY_NOT_EDITABLE409 or 422The key is the publishable key, or it was revoked or expired.
KEY_SCOPES_FIXED422Only a restricted key's scopes can change.
KEY_ALREADY_ROLLED409The key was rolled, so its expiry can't change.

Roll an API key

Replaces a key without downtime. The new key has the same name, type, scopes and lifetime, and its full value is returned once, in secret. The old key keeps working for the overlap you choose, never past its own expiry, then stops.

MethodPathScopeIdempotency-Key
POST/v1/api-keys/{id}/rolloperations:managementRequired

Also available as abusezero api-keys roll in the AbuseZero CLI, abusezero_roll_api_key on the AbuseZero MCP server and rollApiKey() in the AbuseZero Node.js SDK.

  • The workspace owner and admins, and the old key's creator, get the Key rolled email. It says when the old key stops working.
  • Sending the same request again with the same Idempotency-Key returns SECRET_ALREADY_SHOWN.

Body parameters

ParameterTypeRequiredDescription
overlap_hours1, 24 or 168YesHow long the old key keeps working: 1 hour, 24 hours or 7 days.

Example

const replacement = await abusezero.rollApiKey("73492810562018437529", { overlap_hours: 24 }, "roll-production-key");
// Deploy replacement.secret before replacement.previous.expires_at.

Response

Returns 201 with the new key's API key object, its secret, and previous: the old key's id and the expires_at when it stops working.

Errors

CodeStatusMeaning
KEY_NOT_FOUND404No key with this ID exists in the workspace.
KEY_NOT_EDITABLE409 or 422The key is the publishable key, or it was revoked or expired.
KEY_ALREADY_ROLLED409The key was already rolled. Roll its replacement instead.
SECRET_ALREADY_SHOWN409This request already rolled the key, and the new secret isn't shown again.

Show a replacement key

When AbuseZero replaces a key for you, the replacement's full value is kept so it can be shown once, and the key's replacement_available is true. This returns the value in secret and then removes it, as Show replacement key does in the dashboard. Store it in your secret store straight away.

MethodPathScopeIdempotency-Key
POST/v1/api-keys/{id}/replacementoperations:managementRequired

Also available as abusezero api-keys replacement in the AbuseZero CLI, abusezero_show_api_key_replacement on the AbuseZero MCP server and showApiKeyReplacement() in the AbuseZero Node.js SDK.

  • With an OAuth token, the signed-in member needs the Create and revoke keys permission.
  • Every reveal is recorded in the audit trail.
  • Sending the same request again with the same Idempotency-Key returns SECRET_ALREADY_SHOWN.

Example

const key = await abusezero.showApiKeyReplacement("73492810562018437529", "show-replacement-key");
// key.secret holds the full key. Store it now: it isn't shown again.

Response

Returns 201 with the API key object and its secret. replacement_available is now false.

Errors

CodeStatusMeaning
RESOURCE_NOT_FOUND404The key has no replacement to show, or it was already shown.
SECRET_ALREADY_SHOWN409This request already showed the replacement once.

Revoke an API key

Revokes a secret or restricted key. It stops working at once, and requests with it fail with INVALID_API_KEY. The publishable key can't be revoked.

MethodPathScopeIdempotency-Key
POST/v1/api-keys/{id}/revokeoperations:managementRequired

Also available as abusezero api-keys revoke in the AbuseZero CLI, abusezero_revoke_api_key on the AbuseZero MCP server and revokeApiKey() in the AbuseZero Node.js SDK.

Example

const key = await abusezero.revokeApiKey("73492810562018437529", "revoke-old-key");

Response

Returns 201 with the API key object, with status revoked.

Errors

CodeStatusMeaning
KEY_NOT_FOUND404No key with this ID exists in the workspace.
KEY_NOT_EDITABLE422The key is the publishable key.

For every other code, see REST API errors.

How is this guide?

Last updated on