M2M API clients

An M2M API client is a credential for automation. Unlike an API key, which is a long-lived bearer token, a client exchanges a secret for a short-lived token and always carries an explicit list of scopes.

Use one when a deploy pipeline, a Terraform run or an internal service needs API access with a small blast radius and a rotatable credential.

Create one

In the dashboard, go to Settings → API clients → New client. Name it after what uses it, tick the scopes it needs and click Create client, then copy the Client ID and the secret. The Client credentials dialog also shows a ready-made token request for your client.

Creating, rotating and revoking clients takes a signed-in Admin or Super Admin with a verified email address, so they happen in the dashboard; API keys cannot manage clients.

An account can hold 20 active clients. Revoke an unused one to make room.

Get a token, then call the API

Authentication is a standard OAuth2 client-credentials exchange against the token endpoint shown in the dashboard with your client. Do not hardcode that URL; copy it from there.

Exchange the secret for an access token.
Terminal window
```
curl -X POST "$TOKEN_ENDPOINT" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=read:monitors write:incidents"
```
$CLIENT_ID, $CLIENT_SECRET and $TOKEN_ENDPOINT are the client_id, client_secret and token_endpoint from the create response. You get back a standard OAuth2 token response (no data envelope) with an access_token. Scopes are space-separated.
Call the Site Qwality API with it, exactly like any other bearer token. Each client can make 600 requests a minute (rate limits).
Terminal window
```
curl https://api.siteqwality.com/http/jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
Refresh when it expires. Tokens are short-lived; request a new one rather than caching indefinitely.

Scopes

Scopes are read:<family> or write:<family>. Twelve families exist:

Family	Covers
`monitors`	HTTP, TCP port, ping, TLS, DNS, cron and browser checks, and reports
`incidents`	Incidents (including those on a status page, under `/status_page/{id}/incident`), escalation policies, on-call schedules, maintenance windows
`notifications`	Notification channels and groups, and reading integrations
`status_pages`	Status pages with their components, layout, scheduled maintenance, subscribers, branding and custom domain
`logs`	Log query, parsers, saved views
`metrics`	Metric query endpoints and saved views
`traces`	Trace search and detail
`errors`	Errors and their issue workflow
`rum`	RUM applications and analytics
`dashboards`	Dashboards, templates, version history, share links and widget queries
`services`	Services and the escalation policy each one routes to
`users`	Each user’s contact methods and notification rules, for provisioning on-call

write covers POST, PUT, PATCH and DELETE. Everything else is read. Granting write does not imply read; if a client needs both, grant both.

One scope sits outside the families: read:rum_replay lets a client watch session replays. It is never implied, not by read:rum and not by a key with no scope list, so a client that downloads replays needs both read:rum and read:rum_replay.

read:audit lets a client read the audit log. It is never implied either.

integrations:manage also sits outside the families. Adding, changing or deleting an integration needs it, because each integration holds a credential; write:notifications does not cover those writes. Reading integrations stays under read:notifications, with credentials masked.

Scope checking is fail-closed. No family covers account management, billing, authentication, staff endpoints or webhooks, so a client is refused there whatever scopes it holds. That includes managing API clients: a client can never mint another client, so a signed-in Admin or Super Admin manages clients. The users family does not invite, remove or change the role of anyone on the team.

The partner client-management endpoints need the Admin role, and a client carries no role, so it cannot use them. A client can act inside a partner’s client account with the X-SQ-Account header, subject to its scopes.

A 403 reading Insufficient scopes means the client lacks the scope; This endpoint is not available to M2M API clients means no family covers the endpoint.

Rotate a secret

Under Settings → API clients, click the rotate icon on the client’s card and confirm with Rotate secret.

Rotation is immediate and has no overlap window: the old secret stops working at once and the new one is shown once, so put it in place straight away. To switch without a gap, create a second client with the same scopes, move your automation to it, then revoke the first.

Revoke a client

Under Settings → API clients, click the trash icon on the client’s card and confirm with Revoke client.

Revocation takes effect immediately: an already-issued token is refused on its next request to the Site Qwality API. The token stays valid at the identity provider until it expires, so revocation means “this client can no longer reach Site Qwality”, not “this token is destroyed everywhere”.

Other behavior

A suspended account can still read through a client but cannot make changes.
Every mutating call a client makes is recorded in the audit log with actor type m2m and the client’s ID.
There is no “fetch one client” endpoint; list them and filter.