Clerk API (unofficial showcase)
POST/m2m_tokens

Create an M2M token

Creates a new M2M token for the machine associated with the Machine Secret Key used to authenticate the request. Use token_format to choose opaque or JWT format and seconds_until_expiration to set the token lifetime. Set min_remaining_ttl_seconds to reuse an eligible existing opaque token instead of minting a new one.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

4 body fields

Configuration for the M2M token to create. All fields are optional.

token_formatstringoptional
Token format: `opaque` or `jwt`. Defaults to `opaque` when omitted.
Allowed:opaquejwtDefault:opaque
seconds_until_expirationnumberoptional
Token lifetime in seconds. Must be greater than 0.
claimsunknownoptional
Claims to include in the token.
min_remaining_ttl_secondsintegeroptional
Enables server-side token reuse for opaque-format tokens. When set, if a non-revoked, non-expired M2M token already exists for this machine with identical `claims` and `scopes` and at least this many seconds of remaining lifetime, that existing token is returned and no new token is minted. Use this when caching tokens in application memory across requests is impractical — for example, in serverless functions, short-lived job workers, or autoscaling containers that churn faster than the token TTL. Pooling at the server collapses many redundant create calls into reuse of a single live token, which is the recommended pattern for high-volume M2M traffic. Must be strictly less than the effective token lifetime — that is, `seconds_until_expiration` when provided, or the machine's default TTL otherwise. A value greater than or equal to the lifetime is rejected with a 400, since no freshly-minted token would ever satisfy the requirement. Only applies to opaque-format tokens (`token_format` defaults to `opaque`). JWT-format tokens are stateless and are never deduplicated.

3 status codes
201Returns the created M2M token object, including its token value, identifier, machine subject, scopes, claims, and expiration details.
objectstringrequired
Allowed:machine_to_machine_token
idstringrequired
subjectstringrequired
claimsunknownoptional
scopesarray<string>optional
Default:[]
tokenstringrequired
revokedbooleanrequired
revocation_reasonstringrequired
expiredbooleanrequired
expirationnumberrequired
The timestamp for when the token will expire, in milliseconds
last_used_atnumberrequired
The timestamp for when the token was last used, in milliseconds
created_atnumberrequired
The timestamp for when the token was created, in milliseconds
updated_atnumberrequired
The timestamp for when the token was last updated, in milliseconds
400Returned when the request fails validation, such as when a token format or expiration value is invalid.
errorsarray<object>required
409Returned when token creation conflicts with the current state.
errorsarray<object>required

Error handling

A 400 is returned when the request fails validation, and a 409 when token creation conflicts with the current state. Authenticate with a Machine Secret Key. token_format must be opaque or jwt, seconds_until_expiration must be greater than 0, and min_remaining_ttl_seconds must be an integer of 0 or greater.