Stytch Passwordless Authentication

naftiko: "1.0.0-alpha1"

info:
  label: "Stytch Passwordless Authentication"
  description: >-
    Unified capability for passwordless authentication workflows using Stytch's Consumer API.
    Combines magic links, OTP, and session management to deliver secure login flows without passwords.
    Used by consumer app developers building user authentication.
  tags:
    - Stytch
    - Authentication
    - Passwordless
    - Magic Links
    - OTP
    - Consumer
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      STYTCH_PROJECT_ID: STYTCH_PROJECT_ID
      STYTCH_SECRET: STYTCH_SECRET

capability:
  consumes:
    - import: stytch-consumer
      location: ./shared/consumer-auth.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: stytch-passwordless-api
      description: "Unified REST API for Stytch passwordless authentication workflows."
      resources:
        - path: /v1/magic-links/send
          name: magic-link-send
          description: "Send email magic links"
          operations:
            - method: POST
              name: send-magic-link
              description: "Send a magic link for authentication"
              call: "stytch-consumer.send-magic-link"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/magic-links/authenticate
          name: magic-link-authenticate
          description: "Authenticate magic link tokens"
          operations:
            - method: POST
              name: authenticate-magic-link
              description: "Authenticate with a magic link token"
              call: "stytch-consumer.authenticate-magic-link"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/otps/sms/send
          name: otp-sms-send
          description: "Send SMS OTP"
          operations:
            - method: POST
              name: send-otp-sms
              description: "Send a one-time passcode via SMS"
              call: "stytch-consumer.send-otp-sms"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/otps/authenticate
          name: otp-authenticate
          description: "Authenticate OTP codes"
          operations:
            - method: POST
              name: authenticate-otp
              description: "Authenticate with a one-time passcode"
              call: "stytch-consumer.authenticate-otp"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/sessions/authenticate
          name: session-authenticate
          description: "Session validation"
          operations:
            - method: POST
              name: authenticate-session
              description: "Validate a session token"
              call: "stytch-consumer.authenticate-session"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/sessions/revoke
          name: session-revoke
          description: "Session revocation"
          operations:
            - method: POST
              name: revoke-session
              description: "Revoke a session"
              call: "stytch-consumer.revoke-session"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/users/{user_id}
          name: user
          description: "User records"
          operations:
            - method: GET
              name: get-user
              description: "Get a user"
              call: "stytch-consumer.get-user"
              with:
                user_id: "rest.user_id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: stytch-passwordless-mcp
      transport: http
      description: "MCP server for AI-assisted Stytch passwordless authentication."
      tools:
        - name: send-magic-link
          description: "Send a Stytch magic link to a user's email for passwordless login"
          hints:
            readOnly: false
            destructive: false
          call: "stytch-consumer.send-magic-link"
          outputParameters:
            - type: object
              mapping: "$."
        - name: authenticate-magic-link
          description: "Complete Stytch magic link authentication using the token from the email"
          hints:
            readOnly: false
            destructive: false
          call: "stytch-consumer.authenticate-magic-link"
          outputParameters:
            - type: object
              mapping: "$."
        - name: send-otp-sms
          description: "Send a Stytch SMS one-time passcode to a phone number"
          hints:
            readOnly: false
            destructive: false
          call: "stytch-consumer.send-otp-sms"
          outputParameters:
            - type: object
              mapping: "$."
        - name: authenticate-otp
          description: "Authenticate a user with a Stytch one-time passcode"
          hints:
            readOnly: false
            destructive: false
          call: "stytch-consumer.authenticate-otp"
          outputParameters:
            - type: object
              mapping: "$."
        - name: authenticate-session
          description: "Validate a Stytch consumer session token or JWT"
          hints:
            readOnly: true
            idempotent: true
          call: "stytch-consumer.authenticate-session"
          outputParameters:
            - type: object
              mapping: "$."
        - name: revoke-session
          description: "Revoke an active Stytch consumer session (logout)"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "stytch-consumer.revoke-session"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-user
          description: "Retrieve a Stytch user record by ID"
          hints:
            readOnly: true
          call: "stytch-consumer.get-user"
          with:
            user_id: "tools.user_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-users
          description: "Search Stytch users"
          hints:
            readOnly: true
            openWorld: true
          call: "stytch-consumer.search-users"
          outputParameters:
            - type: object
              mapping: "$."