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"
}| Field | Type | Description |
|---|---|---|
object | "api_key" | The object type. |
id | string | The key's ID. Request logs name it as api_key. |
name | string | The key's name. |
type | secret, restricted or publishable | A 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. |
scopes | array of strings | The scopes the key holds. |
prefix | string or null | The start of the key: sk_, rk_ or pk_. |
last_four | string or null | The key's last four characters, to tell keys apart. |
value | string or null | The publishable key's full value, which is safe in page source. null for every other key. |
status | active, expired or revoked | Whether the key still works. |
replacement_available | boolean | Whether AbuseZero replaced this key for you and its value can be shown once. |
expires_at | string or null | When the key stops working. null means it never expires. |
last_used_at | string or null | When the key last made a request, within a minute. |
created_at | string | When 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
GET | /v1/api-keys | operations:general | Not 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
| Parameter | Type | Required | Limits | Description |
|---|---|---|---|---|
limit | integer | No | 1 to 100, default 50 | How many keys to return. |
cursor | string | No | The 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/api-keys | operations:management | Required |
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:generalandoperations:configuration, neveroperations: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-KeyreturnsSECRET_ALREADY_SHOWN, because the secret is shown once. To get another key, send a new request with a new key.
Body parameters
| Parameter | Type | Required | Limits | Description |
|---|---|---|---|---|
name | string | Yes | 1 to 80 characters | The key's name. |
type | secret or restricted | Yes | The key's type. It never changes. | |
scopes | array of strings | For restricted keys | operations:general, operations:configuration or both | The scopes a restricted key holds. Leave it out for a secret key. |
expires_in_days | integer or null | No | 1 to 3,650, default null | Whole 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
| Code | Status | Meaning |
|---|---|---|
KEY_PERMISSION_DENIED | 403 | The request used an API key. Use an OAuth sign-in or a machine client. |
PERMISSION_REQUIRED | 403 | With an OAuth token, the signed-in member doesn't have Create and revoke keys. |
KEY_SCOPE | 422 | scopes includes operations:management or observations:create. |
SCOPE_REQUIRED | 422 | A restricted key needs at least one scope. |
INVALID_EXPIRY | 422 | expires_in_days is outside 1 to 3,650. |
SECRET_ALREADY_SHOWN | 409 | This 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
PATCH | /v1/api-keys/{id} | operations:management | Required |
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.
| Parameter | Type | Required | Limits | Description |
|---|---|---|---|---|
name | string | No | 1 to 80 characters | The key's new name. |
scopes | array of strings | No | operations:general, operations:configuration or both | A restricted key's new scopes. |
expires_in_days | integer or null | No | 1 to 3,650 | Whole 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
| Code | Status | Meaning |
|---|---|---|
KEY_NOT_FOUND | 404 | No key with this ID exists in the workspace. |
KEY_NOT_EDITABLE | 409 or 422 | The key is the publishable key, or it was revoked or expired. |
KEY_SCOPES_FIXED | 422 | Only a restricted key's scopes can change. |
KEY_ALREADY_ROLLED | 409 | The 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/api-keys/{id}/roll | operations:management | Required |
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-KeyreturnsSECRET_ALREADY_SHOWN.
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
overlap_hours | 1, 24 or 168 | Yes | How 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
| Code | Status | Meaning |
|---|---|---|
KEY_NOT_FOUND | 404 | No key with this ID exists in the workspace. |
KEY_NOT_EDITABLE | 409 or 422 | The key is the publishable key, or it was revoked or expired. |
KEY_ALREADY_ROLLED | 409 | The key was already rolled. Roll its replacement instead. |
SECRET_ALREADY_SHOWN | 409 | This 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/api-keys/{id}/replacement | operations:management | Required |
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-KeyreturnsSECRET_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
| Code | Status | Meaning |
|---|---|---|
RESOURCE_NOT_FOUND | 404 | The key has no replacement to show, or it was already shown. |
SECRET_ALREADY_SHOWN | 409 | This 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/api-keys/{id}/revoke | operations:management | Required |
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
| Code | Status | Meaning |
|---|---|---|
KEY_NOT_FOUND | 404 | No key with this ID exists in the workspace. |
KEY_NOT_EDITABLE | 422 | The key is the publishable key. |
For every other code, see REST API errors.
Related
How is this guide?
Last updated on