Stytch TOTP Authenticator Enrollment

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
arazzo: 1.0.1
info:
  title: Stytch TOTP Authenticator Enrollment
  summary: Create a user, register a TOTP authenticator, and authenticate the first code.
  description: >-
    An authenticator-app (TOTP) enrollment flow for consumer apps. The workflow
    creates a user, generates a TOTP secret and QR code for that user to scan
    into their authenticator app, and then authenticates the first generated
    TOTP code to confirm enrollment and mint a session. Every step spells out its
    request inline so the flow can be read and executed without opening the
    underlying OpenAPI description. All calls authenticate with HTTP Basic auth
    using your Stytch project_id as the username and secret as the password.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-620.20
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-620.20
      capability_name: Identity & Access Management
      spec: stytch-user-api-openapi.yml
      confidence: 0.75
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: totpApi
  url: ../openapi/stytch-totp-api-openapi.yml
  type: openapi
- name: userApi
  url: ../openapi/stytch-user-api-openapi.yml
  type: openapi
workflows:
- workflowId: totp-enrollment
  summary: Create a user, generate a TOTP secret, and authenticate the first code.
  description: >-
    Provisions a user, creates a TOTP registration returning a secret and QR
    code, then verifies the first authenticator code to complete enrollment and
    obtain a session.
  inputs:
    type: object
    required:
    - email
    - totp_code
    properties:
      email:
        type: string
        description: The email address to create the enrolling user under.
      totp_code:
        type: string
        description: The first TOTP code generated by the user's authenticator app.
      session_duration_minutes:
        type: integer
        description: Optional session lifetime in minutes for the authenticated session.
  steps:
  - stepId: createUser
    description: >-
      Add a new user to Stytch to enroll into TOTP, returning the user_id.
    operationId: api_user_v1_Create
    requestBody:
      contentType: application/json
      payload:
        email: $inputs.email
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      userId: $response.body#/user_id
  - stepId: createTotp
    description: >-
      Create a TOTP registration for the user, returning the shared secret, QR
      code, and recovery codes for the authenticator app to scan.
    operationId: api_totp_v1_Create
    requestBody:
      contentType: application/json
      payload:
        user_id: $steps.createUser.outputs.userId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      totpId: $response.body#/totp_id
      secret: $response.body#/secret
      qrCode: $response.body#/qr_code
      recoveryCodes: $response.body#/recovery_codes
  - stepId: authenticateTotp
    description: >-
      Authenticate the first TOTP code generated by the authenticator app to
      confirm enrollment and mint a session.
    operationId: api_totp_v1_Authenticate
    requestBody:
      contentType: application/json
      payload:
        user_id: $steps.createUser.outputs.userId
        totp_code: $inputs.totp_code
        session_duration_minutes: $inputs.session_duration_minutes
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      userId: $response.body#/user_id
      sessionToken: $response.body#/session_token
      sessionJwt: $response.body#/session_jwt
  outputs:
    userId: $steps.authenticateTotp.outputs.userId
    totpId: $steps.createTotp.outputs.totpId
    sessionToken: $steps.authenticateTotp.outputs.sessionToken