M2M Tokens

Create a M2M Token

Changed on

Creates a new M2M Token. Must be authenticated via a Machine Secret Key.

post/m2m_tokens

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/m2m_tokens
  • Auth: HTTP bearer

Request body

token_format'opaque' | 'jwt'
seconds_until_expirationnumber nullable
claimsunknown
min_remaining_ttl_secondsinteger

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.

Example request

{
  "min_remaining_ttl_seconds": 240
}

Response

201 Created

object'machine_to_machine_token' required
idstring required
subjectstring required
claimsunknown
scopesstring[]
tokenstring required
revokedboolean required
revocation_reasonstring nullable required
expiredboolean required
expirationnumber nullable required

The timestamp for when the token will expire, in milliseconds

last_used_atnumber nullable required

The timestamp for when the token was last used, in milliseconds

created_atnumber required

The timestamp for when the token was created, in milliseconds

updated_atnumber required

The timestamp for when the token was last updated, in milliseconds

Example response

{
  "id": "mt_f7f0ba8c3b4843ce7d85fcdd5e71853e",
  "subject": "mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk",
  "claims": {
    "important_metadata": "Some useful data"
  },
  "scopes": [
    "mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk",
    "mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em"
  ],
  "token": "mt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "revocation_reason": "Revoked by user",
  "expiration": 1716883200000,
  "last_used_at": 1716883200000,
  "created_at": 1716883200000,
  "updated_at": 1716883200000
}

Changes