Clerk

Clerk Machines API

A Machine represents a machine/server/service which can be used in machine-to-machine authentication.

GitHub OpenAPI
Business capability
Identity & Access Management BC-620.20

Operations 9

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

GET /machines List machines in an instance · Get a List of Machines for an Instance #
Ask an LLM
“Which machines have been set up for machine-to-machine auth in my instance?”
“Can I search machines by name and sort the results?”
Tell an agent
List all machines in my instance.
Search machines matching {query}.
POST /machines Create a machine identity · Create a Machine #
Ask an LLM
“How do I register a new service as a machine for M2M tokens?”
“Can I set a default token lifetime when creating a machine?”
Tell an agent
Create a machine named {name}.
Create machine {name} with default token TTL {default_token_ttl}.
GET /machines/{machine_id} Retrieve a machine · Retrieve a Machine #
Ask an LLM
“How do I see the details of one machine?”
“What is the configured default token TTL on a given machine?”
Tell an agent
Show machine {machine_id}.
Get the details of machine {machine_id}.
PATCH /machines/{machine_id} Rename or reconfigure a machine · Update a Machine #
Ask an LLM
“How do I rename an existing machine?”
“Can I change a machine's default token lifetime after creating it?”
Tell an agent
Rename machine {machine_id} to {name}.
Set the default token TTL of machine {machine_id} to {default_token_ttl}.
DELETE /machines/{machine_id} Delete a machine · Delete a Machine #
Ask an LLM
“How do I remove a machine that is no longer used?”
“Can I delete a machine identity for a decommissioned service?”
Tell an agent destructive · confirm first
Delete machine {machine_id}.
Remove decommissioned machine {machine_id}.
GET /machines/{machine_id}/secret_key Get a machine's secret key · Retrieve a Machine Secret Key #
Ask an LLM
“Where do I find the secret key for a machine so my service can authenticate?”
“How do I read back the current secret of a machine?”
Tell an agent
Get the secret key for machine {machine_id}.
Show the current secret of machine {machine_id}.
POST /machines/{machine_id}/secret_key/rotate Rotate a machine's secret key · Rotate a Machine's Secret Key #
Ask an LLM
“How do I rotate a machine secret without breaking services immediately?”
“How long does the previous machine secret keep working after rotation?”
Tell an agent
Rotate the secret key of machine {machine_id}, keeping the old one valid for {previous_token_ttl} seconds.
Issue a fresh secret for machine {machine_id} with a {previous_token_ttl}-second grace period for the old one.
POST /machines/{machine_id}/scopes Allow one machine to access another · Create a Machine Scope #
Ask an LLM
“How do I let one machine call another machine?”
“Is there a limit on how many scopes a machine can have?”
Tell an agent
Allow machine {machine_id} to access machine {to_machine_id}.
Grant machine {machine_id} a scope to call {to_machine_id}.
DELETE /machines/{machine_id}/scopes/{other_machine_id} Remove one machine's access to another · Delete a Machine Scope #
Ask an LLM
“How do I stop a machine from calling another machine?”
“Can I revoke a machine-to-machine scope between two services?”
Tell an agent destructive · confirm first
Remove machine {machine_id}'s access to machine {other_machine_id}.
Delete the scope letting {machine_id} call {other_machine_id}.

Documentation

📖
Documentation
https://clerk.com/docs/reference/backend-api
📖
APIReference
https://clerk.com/docs/reference/backend-api
📖
GettingStarted
https://clerk.com/docs/quickstarts/overview
📖
Authentication
https://clerk.com/docs/backend-requests/making/jwt-templates
📖
Documentation
https://clerk.com/docs
📖
Documentation
https://clerk.com/docs/webhooks/overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-machines-api-openapi.yml

Other Resources

🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/rules/clerk-rules.yml

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:clerk-com-machines-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

clerk-com-machines-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Backend Machines 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: Machines
  description: A Machine represents a machine/server/service which can be used in machine-to-machine authentication.
paths:
  /machines:
    get:
      operationId: ListMachines
      x-speakeasy-group: machines
      x-speakeasy-name-override: list
      summary: Get a List of Machines for an Instance
      description: 'This request returns the list of machines for an instance. The machines are

        ordered by descending creation date (i.e. most recent machines will be

        returned first)'
      tags:
      - Machines
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: query
        name: query
        description: Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name.
        schema:
          type: string
        allowEmptyValue: true
        required: false
      - in: query
        name: order_by
        description: 'Allows to return machines in a particular order.

          You can order the returned machines by their `name` or `created_at`.

          To specify the direction, use the `+` or `-` symbols prepended to the property to order by.

          For example, to return machines in descending order by `created_at`, use `-created_at`.

          If you don''t use `+` or `-`, then `+` is implied.

          Defaults to `-created_at`.'
        schema:
          type: string
          default: -created_at
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Machine.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateMachine
      x-speakeasy-group: machines
      x-speakeasy-name-override: create
      summary: Create a Machine
      description: Creates a new machine.
      tags:
      - Machines
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the machine
                  minLength: 1
                  maxLength: 255
                scoped_machines:
                  type: array
                  items:
                    type: string
                  description: Array of machine IDs that this machine will have access to. Maximum of 150 scopes per machine.
                  maxItems: 150
                default_token_ttl:
                  type: integer
                  description: The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.
                  minimum: 1
                  maximum: 315360000
                  default: 3600
      responses:
        '200':
          $ref: '#/components/responses/Machine.Created'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /machines/{machine_id}:
    get:
      operationId: GetMachine
      x-speakeasy-group: machines
      x-speakeasy-name-override: get
      summary: Retrieve a Machine
      description: Returns the details of a machine.
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Machine'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      operationId: UpdateMachine
      x-speakeasy-group: machines
      x-speakeasy-name-override: update
      summary: Update a Machine
      description: 'Updates an existing machine.

        Only the provided fields will be updated.'
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the machine
                  minLength: 1
                  maxLength: 255
                default_token_ttl:
                  type: integer
                  description: The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.
                  minimum: 1
                  maximum: 315360000
      responses:
        '200':
          $ref: '#/components/responses/Machine'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteMachine
      x-speakeasy-group: machines
      x-speakeasy-name-override: delete
      summary: Delete a Machine
      description: Deletes a machine.
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine to delete
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Machine.Deleted'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /machines/{machine_id}/secret_key:
    get:
      operationId: GetMachineSecretKey
      x-speakeasy-group: machines
      x-speakeasy-name-override: getSecretKey
      summary: Retrieve a Machine Secret Key
      description: Returns the secret key for a machine.
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine to retrieve the secret key for
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Machine.SecretKey'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /machines/{machine_id}/secret_key/rotate:
    post:
      operationId: RotateMachineSecretKey
      x-speakeasy-group: machines
      x-speakeasy-name-override: rotateSecretKey
      summary: Rotate a Machine's Secret Key
      description: 'Rotates the machine''s secret key.

        When the secret key is rotated, make sure to update it in your machine/application.

        The previous secret key will remain valid for the duration specified by the previous_token_ttl parameter.'
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine to rotate the secret key for
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - previous_token_ttl
              properties:
                previous_token_ttl:
                  type: integer
                  minimum: 0
                  maximum: 28800
                  description: 'The time in seconds that the previous secret key will remain valid after rotation.

                    This ensures a graceful transition period for updating applications with the new secret key.

                    Set to 0 to immediately expire the previous key. Maximum value is 8 hours (28800 seconds).'
      responses:
        '200':
          $ref: '#/components/responses/Machine.SecretKey'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /machines/{machine_id}/scopes:
    post:
      operationId: CreateMachineScope
      x-speakeasy-group: machines
      x-speakeasy-name-override: createScope
      summary: Create a Machine Scope
      description: 'Creates a new machine scope, allowing the specified machine to access another machine.

        Maximum of 150 scopes per machine.'
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine that will have access to another machine
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - to_machine_id
              properties:
                to_machine_id:
                  type: string
                  description: The ID of the machine that will be scoped to the current machine
      responses:
        '200':
          $ref: '#/components/responses/MachineScope'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /machines/{machine_id}/scopes/{other_machine_id}:
    delete:
      operationId: DeleteMachineScope
      x-speakeasy-group: machines
      x-speakeasy-name-override: deleteScope
      summary: Delete a Machine Scope
      description: Deletes a machine scope, removing access from one machine to another.
      tags:
      - Machines
      parameters:
      - name: machine_id
        in: path
        description: The ID of the machine that has access to another machine
        required: true
        schema:
          type: string
      - name: other_machine_id
        in: path
        description: The ID of the machine that is being accessed
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/MachineScope.Deleted'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    MachineWithoutScopedMachines:
      type: object
      required:
      - object
      - id
      - name
      - instance_id
      - created_at
      - updated_at
      properties:
        object:
          type: string
          enum:
          - machine
        id:
          type: string
          description: Unique identifier for the machine.
        name:
          type: string
          description: The name of the machine.
          maxLength: 255
          minLength: 1
        instance_id:
          type: string
          description: The ID of the instance this machine belongs to.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
        default_token_ttl:
          type: integer
          description: The default time-to-live (TTL) in seconds for tokens created by this machine.
          minimum: 1
          default: 3600
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    Machine:
      allOf:
      - $ref: '#/components/schemas/MachineWithoutScopedMachines'
      - type: object
        required:
        - scoped_machines
        properties:
          scoped_machines:
            type: array
            items:
              $ref: '#/components/schemas/MachineWithoutScopedMachines'
            description: Array of machines this machine has access to.
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    MachineScope:
      type: object
      required:
      - object
      - from_machine_id
      - to_machine_id
      - created_at
      properties:
        object:
          type: string
          enum:
          - machine_scope
        from_machine_id:
          type: string
          description: The ID of the machine that has access to the target machine.
        to_machine_id:
          type: string
          description: The ID of the machine that is being accessed.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
  responses:
    MachineScope.Deleted:
      description: Machine scope deleted successfully for a machine
      content:
        application/json:
          schema:
            type: object
            required:
            - object
            - from_machine_id
            - to_machine_id
            - deleted
            properties:
              object:
                type: string
                enum:
                - machine_scope
                description: String representing the object's type.
              from_machine_id:
                type: string
                description: The ID of the machine that had access to the target machine
              to_machine_id:
                type: string
                description: The ID of the machine that was being accessed
              deleted:
                type: boolean
                enum:
                - true
                description: Whether the machine scope was successfully deleted
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Machine.List:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
            - data
            - total_count
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Machine'
              total_count:
                type: integer
                description: Total number of machines
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Machine.SecretKey:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
            - object
            - secret
            properties:
              object:
                type: string
                enum:
                - machine_secret_key
                description: String representing the object's type.
              secret:
                type: string
                readOnly: true
                description: The secret key for the machine.
    Machine:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Machine'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Machine.Created:
      description: Success
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/Machine'
            - type: object
              required:
              - secret_key
              properties:
                secret_key:
                  type: string
                  readOnly: true
                  description: The secret key for the machine, only returned upon creation.
    MachineScope:
      description: Machine scope created successfully for a machine
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineScope'
    Machine.Deleted:
      description: Success
      content:
        application/json:
          schema:
            type: object
            required:
            - object
            - id
            - deleted
            properties:
              object:
                type: string
                enum:
                - machine
                description: String representing the object's type.
              id:
                type: string
                description: The ID of the deleted machine
              deleted:
                type: boolean
                enum:
                - true
                description: Whether the machine was successfully deleted
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  parameters:
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
  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