Stytch B2B Email OTP Discovery and Exchange

arazzo: 1.0.1
info:
  title: Stytch B2B Email OTP Discovery and Exchange
  summary: Send a discovery email OTP, authenticate the code, then exchange into an organization.
  description: >-
    An organization-discovery login flow driven by email one-time passcodes for
    B2B apps. The workflow sends a discovery email OTP to an address, authenticates
    the code the user enters to obtain an intermediate session and the list of
    organizations the email belongs to, then exchanges that intermediate session
    into a chosen organization to mint a full member 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-email-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: discoveryApi
  url: ../openapi/stytch-discovery-api-openapi.yml
  type: openapi
- name: emailApi
  url: ../openapi/stytch-email-api-openapi.yml
  type: openapi
workflows:
- workflowId: email-otp-discovery
  summary: Send a discovery email OTP, authenticate the code, then exchange into an org.
  description: >-
    Dispatches a discovery email OTP, exchanges the entered code for an
    intermediate session and discovered organizations, then exchanges into the
    chosen organization for a full member session.
  inputs:
    type: object
    required:
    - email_address
    - code
    - organization_id
    properties:
      email_address:
        type: string
        description: The email address to send the discovery passcode to.
      code:
        type: string
        description: The discovery one-time passcode the user received and entered.
      organization_id:
        type: string
        description: The id of the discovered organization to exchange into.
      session_duration_minutes:
        type: integer
        description: Optional session lifetime in minutes for the resulting member session.
  steps:
  - stepId: sendDiscoveryOtp
    description: >-
      Send a discovery email one-time passcode to the address so the user can
      begin the organization discovery flow.
    operationId: api_b2b_otp_v1_b2b_otp_email_discovery_Send
    requestBody:
      contentType: application/json
      payload:
        email_address: $inputs.email_address
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      requestId: $response.body#/request_id
  - stepId: authenticateDiscoveryOtp
    description: >-
      Authenticate the discovery passcode to obtain an intermediate session token
      and the organizations the email already belongs to.
    operationId: api_b2b_otp_v1_b2b_otp_email_discovery_Authenticate
    requestBody:
      contentType: application/json
      payload:
        email_address: $inputs.email_address
        code: $inputs.code
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      intermediateSessionToken: $response.body#/intermediate_session_token
      discoveredOrganizations: $response.body#/discovered_organizations
  - stepId: exchangeIntoOrg
    description: >-
      Exchange the intermediate session token into the chosen organization to
      mint a full member session.
    operationId: api_discovery_v1_discovery_intermediate_sessions_Exchange
    requestBody:
      contentType: application/json
      payload:
        intermediate_session_token: $steps.authenticateDiscoveryOtp.outputs.intermediateSessionToken
        organization_id: $inputs.organization_id
        session_duration_minutes: $inputs.session_duration_minutes
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      memberId: $response.body#/member_id
      organizationId: $response.body#/organization/organization_id
      sessionToken: $response.body#/session_token
  outputs:
    intermediateSessionToken: $steps.authenticateDiscoveryOtp.outputs.intermediateSessionToken
    memberId: $steps.exchangeIntoOrg.outputs.memberId
    organizationId: $steps.exchangeIntoOrg.outputs.organizationId
    sessionToken: $steps.exchangeIntoOrg.outputs.sessionToken