Skip to content
Dashboard
Theme
Theme

Machine-to-machine clients

Issue OAuth client-credentials tokens to your own services and your customers' integrations.

View Markdown

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

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.

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.

  • 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.