# Machine-to-machine clients

A machine client (`mcli_…`) gets access tokens for a service, not a person, with the OAuth 2.0 client credentials grant.

## Create a client

`POST /v1/m2m_clients` with a `name`, one or more `audiences` (the APIs its tokens are for), optional `scopes`, an optional `organization` to limit it to one customer, and `access_token_seconds` (60 to 3600, default 600). The answer contains the `client_secret` once. Scope: `machine_clients:write`.

Clients authenticate with either:

- `client_secret`, in the body or with HTTP Basic, never both; or
- `private_key_jwt`: a signed assertion checked against the 1 to 10 public keys you register (`RS256`, `PS256`, `ES256` or `EdDSA`). The assertion's `iss` and `sub` are the client ID, `aud` names the token endpoint, it expires within 5 minutes and each `jti` works once.

## Get a token

`POST https://login.ohauthcat.com/user_management/token` with `grant_type=client_credentials`, the client's credentials and optionally `resource` (one of its audiences) and `scope`. The token is an RFC 9068 JWT (`typ: at+jwt`) with `iss`, `aud` (exactly one audience), `sub` and `client_id` (the client ID), `scope`, `jti`, `env` and, for organization clients, `org_id`. There is no refresh token; ask for a new one.

## Rotate and revoke

- `POST /v1/m2m_clients/{client}/rotate_secret` returns a new secret; with `keep_previous`, the old one keeps working for 24 hours.
- `DELETE /v1/m2m_clients/{client}` revokes the client; its next token request fails.

Each client may request 10 tokens a second (bursts of 50). Secrets never appear in logs, audit entries, events or error messages.
