Stytch Email One-Time Passcode Login

arazzo: 1.0.1
info:
  title: Stytch Email One-Time Passcode Login
  summary: Send an email one-time passcode, authenticate the code, and read the session.
  description: >-
    A passwordless email OTP login flow for consumer apps. The workflow sends a
    one-time passcode to an email address (creating the user if they do not yet
    exist), authenticates the method_id and code the user submits, and then reads
    the resulting session back to confirm it is active. 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-session-api-openapi.yml
      confidence: 0.8
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: otpApi
  url: ../openapi/stytch-otp-api-openapi.yml
  type: openapi
- name: sessionApi
  url: ../openapi/stytch-session-api-openapi.yml
  type: openapi
workflows:
- workflowId: email-otp-login
  summary: Send an email OTP, authenticate the code, and verify the session.
  description: >-
    Dispatches a one-time passcode to the supplied email, exchanges the
    method_id and user-entered code for a session, then reads the active
    sessions for the user.
  inputs:
    type: object
    required:
    - email
    - code
    properties:
      email:
        type: string
        description: The email address to send the one-time passcode to.
      code:
        type: string
        description: The one-time passcode the user received and entered.
      session_duration_minutes:
        type: integer
        description: Optional session lifetime in minutes for the authenticated session.
  steps:
  - stepId: sendEmailOtp
    description: >-
      Send a one-time passcode to the email address, creating the user if no
      account exists yet, and return the method_id used to authenticate the code.
    operationId: api_otp_v1_otp_email_LoginOrCreate
    requestBody:
      contentType: application/json
      payload:
        email: $inputs.email
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      userId: $response.body#/user_id
      emailId: $response.body#/email_id
  - stepId: authenticateOtp
    description: >-
      Authenticate the one-time passcode using the email_id as the method_id and
      the code the user entered to mint a session.
    operationId: api_otp_v1_Authenticate
    requestBody:
      contentType: application/json
      payload:
        method_id: $steps.sendEmailOtp.outputs.emailId
        code: $inputs.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
  - stepId: getSession
    description: >-
      Read the active sessions for the authenticated user to confirm the session
      is live.
    operationId: api_session_v1_Get
    parameters:
    - name: user_id
      in: query
      value: $steps.authenticateOtp.outputs.userId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      sessions: $response.body#/sessions
  outputs:
    userId: $steps.authenticateOtp.outputs.userId
    sessionToken: $steps.authenticateOtp.outputs.sessionToken
    sessionJwt: $steps.authenticateOtp.outputs.sessionJwt