AbuseZeroAbuseZero

Machine clients

List, create, rotate and revoke your workspace's machine clients with the AbuseZero REST API.

A machine client is a set of OAuth client credentials that belongs to one workspace, for scripts, CI and cloud agents. It can hold any of the three scopes, operations:management included, which only owners and admins can give it. The same clients appear in Developers → OAuth apps, on the Machine clients tab.

Every call on this page needs a member's own OAuth sign-in, such as the AbuseZero CLI: which machine clients you see and change follows your role, as in the dashboard. A machine client gets MEMBER_SIGN_IN_REQUIRED. An API key gets MEMBER_SIGN_IN_REQUIRED for the list, and KEY_PERMISSION_DENIED for creating, rotating and revoking, which need operations:management.

import { AbuseZero } from "abusezero/server";

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

The machine client object

{
  "object": "machine_client",
  "id": "48193057261840375926",
  "name": "Nightly sync",
  "scopes": ["operations:general", "operations:configuration"],
  "member": { "name": "Priya Shah", "email": "priya@example.com", "role": "developer", "you": true, "former": false },
  "created_at": "2026-11-10T09:00:00.000Z",
  "last_used_at": null
}
FieldTypeDescription
object"machine_client"The object type.
idstringThe client ID, which the client sends to get an access token.
namestringThe client's name. It never changes.
scopesarray of stringsThe scopes the client holds. They never change.
memberobject or nullThe member who created it: name, email, role, whether it's you, and former when they've left the workspace.
created_atstringWhen the client was created.
last_used_atstring or nullWhen the client last made a request, within a minute.

The client secret is returned once, in the response that creates the client or rotates its secret.

List machine clients

Returns the workspace's machine clients your role lets you see, newest first. The owner sees every client. An admin sees their own and those created by members who aren't admins or by former members. Everyone else sees only their own.

MethodPathScopeIdempotency-Key
GET/v1/machine-clientsoperations:generalNot used

Also available as abusezero machine-clients list in the AbuseZero CLI, abusezero_list_machine_clients on the AbuseZero MCP server and machineClients() in the AbuseZero Node.js SDK.

Query parameters

ParameterTypeRequiredLimitsDescription
vieweveryone or mineNoDefault everyoneeveryone lists every client your role lets you see. mine lists only the ones you created.
limitintegerNo1 to 100, default 50How many clients to return.
cursorstringNoThe next_cursor from the previous page, unchanged.

Response

Returns 200 with a list of machine client objects.

Create a machine client

Creates a machine client and returns its secret once, in secret, with the token_endpoint and audience it uses to get access tokens.

MethodPathScopeIdempotency-Key
POST/v1/machine-clientsoperations:managementRequired

Also available as abusezero machine-clients create in the AbuseZero CLI, abusezero_create_machine_client on the AbuseZero MCP server and createMachineClient() in the AbuseZero Node.js SDK.

  • The signed-in member needs the Create and revoke keys permission, as in the dashboard. Only the owner and admins can give a client operations:management.
  • The workspace owner, and each admin who can see the client, get an email.
  • Sending the same request again with the same Idempotency-Key returns SECRET_ALREADY_SHOWN, because the secret is shown once.

Body parameters

ParameterTypeRequiredLimitsDescription
namestringYes1 to 80 charactersThe client's name.
scopesarray of stringsYes1 to 3Any of operations:general, operations:configuration and operations:management. operations:management only for the owner and admins.

Example

const client = await abusezero.createMachineClient(
  { name: "Nightly sync", scopes: ["operations:general", "operations:configuration"] },
  "create-nightly-sync",
);
// Store client.id and client.secret now: the secret isn't shown again.

Response

Returns 201 with the machine client object and secret, token_endpoint and audience.

{
  "object": "machine_client",
  "id": "48193057261840375926",
  "name": "Nightly sync",
  "scopes": ["operations:general", "operations:configuration"],
  "member": { "name": "Priya Shah", "email": "priya@example.com", "role": "developer", "you": true, "former": false },
  "created_at": "2026-11-10T09:00:00.000Z",
  "last_used_at": null,
  "secret": "abusezero_cs_…",
  "token_endpoint": "https://auth.abusezero.com/api/auth/oauth2/token",
  "audience": "https://api.abusezero.com"
}

Errors

CodeStatusMeaning
MEMBER_SIGN_IN_REQUIRED403The request used a machine client. Use a member's OAuth sign-in.
KEY_PERMISSION_DENIED403The request used an API key. Use a member's OAuth sign-in.
PERMISSION_REQUIRED403The signed-in member doesn't have Create and revoke keys, or asked for operations:management without being the owner or an admin.
INVALID_OAUTH_SCOPE422A scope isn't one of the three server scopes.
SECRET_ALREADY_SHOWN409This request already created a client, and its secret isn't shown again.

Rotate a machine client's secret

Gives the client a new secret, returned once, in secret. The old secret, and every access token issued with it, stop working at once, so deploy the new secret straight away.

MethodPathScopeIdempotency-Key
POST/v1/machine-clients/{id}/rotate-secretoperations:managementRequired

Also available as abusezero machine-clients rotate-secret in the AbuseZero CLI, abusezero_rotate_machine_client_secret on the AbuseZero MCP server and rotateMachineClientSecret() in the AbuseZero Node.js SDK.

Example

curl -X POST https://api.abusezero.com/v1/machine-clients/48193057261840375926/rotate-secret \
  -H "Authorization: Bearer $ABUSEZERO_ACCESS_TOKEN" \
  -H "AbuseZero-Workspace: 59670872302871291997" \
  -H "Idempotency-Key: rotate-nightly-sync"

Response

Returns 201.

{ "object": "machine_client_secret", "id": "48193057261840375926", "secret": "abusezero_cs_…" }

Errors

CodeStatusMeaning
OAUTH_CLIENT_NOT_FOUND404No machine client with this ID that you can see exists in the workspace.
SECRET_ALREADY_SHOWN409This request already rotated the secret, and the new one isn't shown again.

Revoke a machine client

Revokes the client. Its secret and every access token issued to it stop working at once. Members who aren't owners or admins revoke only their own.

MethodPathScopeIdempotency-Key
POST/v1/machine-clients/{id}/revokeoperations:managementRequired

Also available as abusezero machine-clients revoke in the AbuseZero CLI, abusezero_revoke_machine_client on the AbuseZero MCP server and revokeMachineClient() in the AbuseZero Node.js SDK.

Response

Returns 201 with { "object": "deleted", "id": "48193057261840375926", "deleted": true }.

Errors

CodeStatusMeaning
OAUTH_CLIENT_NOT_FOUND404No machine client with this ID that you can see exists in the workspace.

For every other code, see REST API errors.

How is this guide?

Last updated on