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
}| Field | Type | Description |
|---|---|---|
object | "machine_client" | The object type. |
id | string | The client ID, which the client sends to get an access token. |
name | string | The client's name. It never changes. |
scopes | array of strings | The scopes the client holds. They never change. |
member | object or null | The member who created it: name, email, role, whether it's you, and former when they've left the workspace. |
created_at | string | When the client was created. |
last_used_at | string or null | When 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
GET | /v1/machine-clients | operations:general | Not 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
| Parameter | Type | Required | Limits | Description |
|---|---|---|---|---|
view | everyone or mine | No | Default everyone | everyone lists every client your role lets you see. mine lists only the ones you created. |
limit | integer | No | 1 to 100, default 50 | How many clients to return. |
cursor | string | No | The 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/machine-clients | operations:management | Required |
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-KeyreturnsSECRET_ALREADY_SHOWN, because the secret is shown once.
Body parameters
| Parameter | Type | Required | Limits | Description |
|---|---|---|---|---|
name | string | Yes | 1 to 80 characters | The client's name. |
scopes | array of strings | Yes | 1 to 3 | Any 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
| Code | Status | Meaning |
|---|---|---|
MEMBER_SIGN_IN_REQUIRED | 403 | The request used a machine client. Use a member's OAuth sign-in. |
KEY_PERMISSION_DENIED | 403 | The request used an API key. Use a member's OAuth sign-in. |
PERMISSION_REQUIRED | 403 | The signed-in member doesn't have Create and revoke keys, or asked for operations:management without being the owner or an admin. |
INVALID_OAUTH_SCOPE | 422 | A scope isn't one of the three server scopes. |
SECRET_ALREADY_SHOWN | 409 | This 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/machine-clients/{id}/rotate-secret | operations:management | Required |
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
| Code | Status | Meaning |
|---|---|---|
OAUTH_CLIENT_NOT_FOUND | 404 | No machine client with this ID that you can see exists in the workspace. |
SECRET_ALREADY_SHOWN | 409 | This 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.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/machine-clients/{id}/revoke | operations:management | Required |
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
| Code | Status | Meaning |
|---|---|---|
OAUTH_CLIENT_NOT_FOUND | 404 | No machine client with this ID that you can see exists in the workspace. |
For every other code, see REST API errors.
Related
How is this guide?
Last updated on