openapi: 3.0.3 info: title: Clerk Backend Account Portal 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](https://clerk.com/docs/versioning/available-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 nullable: true minimum: 0 exclusiveMinimum: true claims: nullable: true 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: nullable: true 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 nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true 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 nullable: true default: false required: false name: revoked in: query - schema: type: boolean nullable: true 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 nullable: true 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: nullable: true 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 nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true 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 nullable: true 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: nullable: true 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 nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true 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: nullable: true 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 nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true 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__ 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