Stytch Machine-to-Machine Authentication

naftiko: 1.0.0-alpha2
info:
  label: Stytch Machine-to-Machine Authentication
  description: >-
    Issue and validate OAuth 2.0 client-credentials tokens for service-to-service traffic — backend
    workers, CI/CD agents, automated data pipelines, and AI agents acting without a human in the loop.
    Stytch's M2M API mints scoped JWT access tokens against a registered M2M client (client_id +
    client_secret) and rotates them on demand.
  tags:
    - Stytch
    - M2M
    - Service Authentication
    - OAuth
    - Client Credentials
    - AI Agents
  created: '2026-05-22'
  modified: '2026-05-22'
binds:
  - namespace: env
    keys:
      STYTCH_PROJECT_ID: STYTCH_PROJECT_ID
      STYTCH_SECRET: STYTCH_SECRET
capability:
  consumes:
    - type: http
      namespace: stytch-m2m
      baseUri: https://api.stytch.com/v1
      description: Stytch M2M — manage M2M clients and mint short-lived JWT access tokens for service-to-service auth.
      authentication:
        type: basic
        username: '{{STYTCH_PROJECT_ID}}'
        password: '{{STYTCH_SECRET}}'
      resources:
        - name: m2m-clients
          path: /m2m/clients
          description: Create and list M2M clients (each has a client_id + client_secret pair plus a set of allowed scopes).
          operations:
            - name: create-m2m-client
              method: POST
              outputRawFormat: json
              outputParameters:
                - name: client_id
                  type: string
                  value: $.m2m_client.client_id
                - name: client_secret
                  type: string
                  value: $.m2m_client.client_secret
              body:
                type: json
                data:
                  scopes: '{{tools.scopes}}'
                  client_name: '{{tools.client_name}}'
        - name: m2m-token
          path: /public/{{STYTCH_PROJECT_ID}}/oauth2/token
          description: OAuth 2.0 client-credentials token endpoint — exchanges client_id + client_secret for a short-lived JWT access token.
          operations:
            - name: issue-token
              method: POST
              outputRawFormat: json
              outputParameters:
                - name: access_token
                  type: string
                  value: $.access_token
              body:
                type: form
                data:
                  grant_type: client_credentials
                  client_id: '{{tools.client_id}}'
                  client_secret: '{{tools.client_secret}}'
        - name: m2m-secret-rotate
          path: /m2m/clients/{client_id}/secrets/rotate/start
          description: Begin rotation for an M2M client secret — keeps the old secret valid until rotation completes.
          operations:
            - name: rotate-start
              method: POST
              outputRawFormat: json
  workflow:
    - step: register-service
      description: Register the calling service / AI agent as an M2M client with the scopes it needs.
      uses: create-m2m-client
    - step: mint-token
      description: At runtime, the service exchanges its client_id + client_secret for a short-lived JWT access token via the OAuth 2.0 token endpoint.
      uses: issue-token
    - step: rotate-on-incident
      description: If a secret leaks, kick off non-disruptive rotation; rotate-complete and rotate-cancel finish the flow.
      uses: rotate-start