Clerk

Clerk M2M Tokens API

Machine to Machine Tokens are used to manage authentication between Machines.

Documentation GitHub OpenAPI

Business capability

Operations 4

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /m2m_tokens Create a machine-to-machine token · Create a M2M Token #

Ask an LLM

“How does a machine get a token to call another machine's API?”

“Can I choose JWT or opaque format and set an expiry for an M2M token?”

Tell an agent

Create an M2M token that expires in {seconds_until_expiration} seconds.

Issue a machine token in {token_format} format with claims {claims}.

GET /m2m_tokens List M2M tokens for a machine · Get M2M Tokens #

Ask an LLM

“Which machine-to-machine tokens have been issued for a machine?”

“Can I filter a machine's M2M tokens to exclude revoked or expired ones?”

Tell an agent

List M2M tokens for machine {subject}.

Show unexpired, unrevoked opaque tokens issued to {subject}.

POST /m2m_tokens/{m2m_token_id}/revoke Revoke an M2M token · Revoke a M2M Token #

Ask an LLM

“How do I revoke a machine token that leaked?”

“Can JWT-format machine tokens be revoked?”

Tell an agent destructive · confirm first

Revoke M2M token {m2m_token_id}.

Revoke machine token {m2m_token_id} because {revocation_reason}.

POST /m2m_tokens/verify Verify an M2M token · Verify a M2M Token #

Ask an LLM

“How do I check that an incoming machine token is valid?”

“Does verifying an M2M token confirm it has access to my machine?”

Tell an agent

Verify M2M token {token}.

Check whether machine token {token} is valid.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/clerk-com-m2m-tokens-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Clerk Backend M2M Tokens API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Backend API, meant to be accessed by backend servers.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see Clerk API Versions.


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: M2M Tokens
  description: Machine to Machine Tokens are used to manage authentication between Machines.
paths:
  /m2m_tokens:
    post:
      x-speakeasy-group: m2m
      x-speakeasy-name-override: createToken
      operationId: createM2MToken
      summary: Create a M2M Token
      description: Creates a new M2M Token. Must be authenticated via a Machine Secret Key.
      tags:
      - M2M Tokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_format:
                  type: string
                  enum:
                  - opaque
                  - jwt
                  default: opaque
                seconds_until_expiration:
                  type:
                  - number
                  - 'null'
                  exclusiveMinimum: 0
                claims: {}
                min_remaining_ttl_seconds:
                  type: integer
                  minimum: 0
                  description: '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: 240
              additionalProperties: false
      responses:
        '201':
          description: 201 Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - machine_to_machine_token
                  id:
                    type: string
                    pattern: ^mt_[0-9A-Fa-f]{32}$
                    example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e
                  subject:
                    type: string
                    pattern: ^mch_\w{27}$
                    example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                  claims:
                    example:
                      important_metadata: Some useful data
                  scopes:
                    type: array
                    items:
                      type: string
                      pattern: ^mch_\w{27}$
                    default: []
                    example:
                    - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                    - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em
                  token:
                    type: string
                    example: mt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                  revoked:
                    type: boolean
                    example: false
                  revocation_reason:
                    type:
                    - string
                    - 'null'
                    example: Revoked by user
                  expired:
                    type: boolean
                    example: false
                  expiration:
                    type:
                    - number
                    - 'null'
                    description: The timestamp for when the token will expire, in milliseconds
                    example: 1716883200
                  last_used_at:
                    type:
                    - number
                    - 'null'
                    description: The timestamp for when the token was last used, in milliseconds
                    example: 1716883200
                  created_at:
                    type: number
                    description: The timestamp for when the token was created, in milliseconds
                    example: 1716883200
                  updated_at:
                    type: number
                    description: The timestamp for when the token was last updated, in milliseconds
                    example: 1716883200
                required:
                - object
                - id
                - subject
                - token
                - revoked
                - revocation_reason
                - expired
                - expiration
                - last_used_at
                - created_at
                - updated_at
                additionalProperties: false
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: Bad Request
                        long_message:
                          type: string
                          example: 'Invalid ''url_parameter.example'': Failed regex check'
                        code:
                          type: string
                          example: bad_request
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
        '409':
          description: 409 Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: some details about the error
                        long_message:
                          type: string
                          example: some details about the error
                        code:
                          type: string
                          example: some_error_code
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
    get:
      x-speakeasy-group: m2m
      x-speakeasy-name-override: listTokens
      operationId: getM2MTokens
      summary: Get M2M Tokens
      description: 'Fetches M2M tokens for a specific machine.


        Only tokens created with the opaque token format are returned by this endpoint. JWT-format M2M tokens are stateless and are not stored.


        This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.


        - When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved.

        - When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be retrieved.'
      tags:
      - M2M Tokens
      parameters:
      - schema:
          type: string
          pattern: ^mch_\w{27}$
        required: true
        name: subject
        in: query
      - schema:
          type:
          - boolean
          - 'null'
          default: false
        required: false
        name: revoked
        in: query
      - schema:
          type:
          - boolean
          - 'null'
          default: false
        required: false
        name: expired
        in: query
      - schema:
          type: number
          minimum: 1
          maximum: 100
          default: 10
        required: false
        name: limit
        in: query
      - schema:
          type:
          - number
          - 'null'
          minimum: 0
          default: 0
        required: false
        name: offset
        in: query
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  m2m_tokens:
                    type: array
                    items:
                      type: object
                      properties:
                        object:
                          type: string
                          enum:
                          - machine_to_machine_token
                        id:
                          type: string
                          pattern: ^mt_[0-9A-Fa-f]{32}$
                          example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e
                        subject:
                          type: string
                          pattern: ^mch_\w{27}$
                          example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                        claims:
                          example:
                            important_metadata: Some useful data
                        scopes:
                          type: array
                          items:
                            type: string
                            pattern: ^mch_\w{27}$
                          default: []
                          example:
                          - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                          - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em
                        revoked:
                          type: boolean
                          example: false
                        revocation_reason:
                          type:
                          - string
                          - 'null'
                          example: Revoked by user
                        expired:
                          type: boolean
                          example: false
                        expiration:
                          type:
                          - number
                          - 'null'
                          description: The timestamp for when the token will expire, in milliseconds
                          example: 1716883200
                        last_used_at:
                          type:
                          - number
                          - 'null'
                          description: The timestamp for when the token was last used, in milliseconds
                          example: 1716883200
                        created_at:
                          type: number
                          description: The timestamp for when the token was created, in milliseconds
                          example: 1716883200
                        updated_at:
                          type: number
                          description: The timestamp for when the token was last updated, in milliseconds
                          example: 1716883200
                      required:
                      - object
                      - id
                      - subject
                      - revoked
                      - revocation_reason
                      - expired
                      - expiration
                      - last_used_at
                      - created_at
                      - updated_at
                      additionalProperties: false
                  total_count:
                    type: number
                required:
                - m2m_tokens
                - total_count
                additionalProperties: false
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: Bad Request
                        long_message:
                          type: string
                          example: 'Invalid ''url_parameter.example'': Failed regex check'
                        code:
                          type: string
                          example: bad_request
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
        '403':
          description: 403 Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: some details about the error
                        long_message:
                          type: string
                          example: some details about the error
                        code:
                          type: string
                          example: some_error_code
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
        '404':
          description: 404 Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: some details about the error
                        long_message:
                          type: string
                          example: some details about the error
                        code:
                          type: string
                          example: some_error_code
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
  /m2m_tokens/{m2m_token_id}/revoke:
    post:
      x-speakeasy-group: m2m
      x-speakeasy-name-override: revokeToken
      operationId: revokeM2MToken
      summary: Revoke a M2M Token
      description: 'Revokes a M2M Token.


        This endpoint only revokes stored opaque-format M2M tokens. JWT-format M2M tokens are stateless and cannot be revoked.


        This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.


        - When revoking a M2M Token with a Machine Secret Key, the token must managed by the Machine associated with the Machine Secret Key.

        - When revoking a M2M Token with a Clerk Secret Key, any token on the Instance can be revoked.'
      tags:
      - M2M Tokens
      parameters:
      - schema:
          type: string
          pattern: ^mt_[0-9A-Fa-f]{32}$
        required: true
        name: m2m_token_id
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revocation_reason:
                  type:
                  - string
                  - 'null'
              additionalProperties: false
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - machine_to_machine_token
                  id:
                    type: string
                    pattern: ^mt_[0-9A-Fa-f]{32}$
                    example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e
                  subject:
                    type: string
                    pattern: ^mch_\w{27}$
                    example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                  claims:
                    example:
                      important_metadata: Some useful data
                  scopes:
                    type: array
                    items:
                      type: string
                      pattern: ^mch_\w{27}$
                    default: []
                    example:
                    - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                    - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em
                  revoked:
                    type: boolean
                    example: false
                  revocation_reason:
                    type:
                    - string
                    - 'null'
                    example: Revoked by user
                  expired:
                    type: boolean
                    example: false
                  expiration:
                    type:
                    - number
                    - 'null'
                    description: The timestamp for when the token will expire, in milliseconds
                    example: 1716883200
                  last_used_at:
                    type:
                    - number
                    - 'null'
                    description: The timestamp for when the token was last used, in milliseconds
                    example: 1716883200
                  created_at:
                    type: number
                    description: The timestamp for when the token was created, in milliseconds
                    example: 1716883200
                  updated_at:
                    type: number
                    description: The timestamp for when the token was last updated, in milliseconds
                    example: 1716883200
                required:
                - object
                - id
                - subject
                - revoked
                - revocation_reason
                - expired
                - expiration
                - last_used_at
                - created_at
                - updated_at
                additionalProperties: false
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: Bad Request
                        long_message:
                          type: string
                          example: 'Invalid ''url_parameter.example'': Failed regex check'
                        code:
                          type: string
                          example: bad_request
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
        '404':
          description: 404 Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: some details about the error
                        long_message:
                          type: string
                          example: some details about the error
                        code:
                          type: string
                          example: some_error_code
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
  /m2m_tokens/verify:
    post:
      x-speakeasy-group: m2m
      x-speakeasy-name-override: verifyToken
      operationId: verifyM2MToken
      summary: Verify a M2M Token
      description: 'Verifies a M2M Token.


        This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.


        - When verifying a M2M Token with a Machine Secret Key, the token must be granted access to the Machine associated with the Machine Secret Key.

        - When verifying a M2M Token with a Clerk Secret Key, any token on the Instance can be verified.'
      tags:
      - M2M Tokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
              required:
              - token
              additionalProperties: false
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - machine_to_machine_token
                  id:
                    type: string
                    pattern: ^mt_[0-9A-Fa-f]{32}$
                    example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e
                  subject:
                    type: string
                    pattern: ^mch_\w{27}$
                    example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                  claims:
                    example:
                      important_metadata: Some useful data
                  scopes:
                    type: array
                    items:
                      type: string
                      pattern: ^mch_\w{27}$
                    default: []
                    example:
                    - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk
                    - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em
                  revoked:
                    type: boolean
                    example: false
                  revocation_reason:
                    type:
                    - string
                    - 'null'
                    example: Revoked by user
                  expired:
                    type: boolean
                    example: false
                  expiration:
                    type:
                    - number
                    - 'null'
                    description: The timestamp for when the token will expire, in milliseconds
                    example: 1716883200
                  last_used_at:
                    type:
                    - number
                    - 'null'
                    description: The timestamp for when the token was last used, in milliseconds
                    example: 1716883200
                  created_at:
                    type: number
                    description: The timestamp for when the token was created, in milliseconds
                    example: 1716883200
                  updated_at:
                    type: number
                    description: The timestamp for when the token was last updated, in milliseconds
                    example: 1716883200
                required:
                - object
                - id
                - subject
                - revoked
                - revocation_reason
                - expired
                - expiration
                - last_used_at
                - created_at
                - updated_at
                additionalProperties: false
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: Bad Request
                        long_message:
                          type: string
                          example: 'Invalid ''url_parameter.example'': Failed regex check'
                        code:
                          type: string
                          example: bad_request
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
        '404':
          description: 404 Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: some details about the error
                        long_message:
                          type: string
                          example: some details about the error
                        code:
                          type: string
                          example: some_error_code
                      required:
                      - message
                      - long_message
                      - code
                required:
                - errors
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true

Clerk M2M Tokens API

Operations 4

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification