naftiko: 1.0.0-alpha2
info:
  label: Stytch Fraud, Bot Defense & Device Intelligence
  description: >-
    Detect bots, automation, and high-risk devices at authentication time using Stytch's Device
    Fingerprinting (DFP) and fraud rules surface. Look up a fingerprint to retrieve a verdict
    (allow / challenge / block), inspect verdict reasons, and feed adaptive MFA / step-up decisions
    into Magic Link and OTP flows.
  tags:
    - Stytch
    - Fraud
    - Device Fingerprinting
    - Bot Detection
    - Adaptive MFA
    - 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-fraud
      baseUri: https://api.stytch.com/v1
      description: Stytch Fraud & Device Intelligence — fingerprint lookup, verdict reasons, fraud rules.
      authentication:
        type: basic
        username: '{{STYTCH_PROJECT_ID}}'
        password: '{{STYTCH_SECRET}}'
      resources:
        - name: fingerprint-lookup
          path: /fingerprint/lookup
          description: Look up a telemetry_id collected by the Stytch DFP browser/mobile SDK to retrieve a verdict and device intelligence signals.
          operations:
            - name: lookup-fingerprint
              method: POST
              outputRawFormat: json
              outputParameters:
                - name: verdict
                  type: string
                  value: $.verdict.action
                - name: visitor_id
                  type: string
                  value: $.fingerprints.visitor_id
              body:
                type: json
                data:
                  telemetry_id: '{{tools.telemetry_id}}'
        - name: verdict-reasons
          path: /verdict_reasons
          description: List verdict reason codes and their human-readable descriptions so you can surface fraud signals in UX and analytics.
          operations:
            - name: list-verdict-reasons
              method: GET
              outputRawFormat: json
        - name: fraud-rules
          path: /rules
          description: Manage adaptive fraud rules — block, challenge, or allow specific visitor_id, IP, country, or fingerprint patterns.
          operations:
            - name: list-rules
              method: GET
              outputRawFormat: json
            - name: set-rule
              method: POST
              outputRawFormat: json
              body:
                type: json
                data:
                  visitor_id: '{{tools.visitor_id}}'
                  action: '{{tools.action}}'
  workflow:
    - step: collect-telemetry
      description: Embed Stytch's DFP SDK in the browser / mobile app to collect a telemetry_id during signup or sign-in.
      external: 'https://stytch.com/docs/fraud/sdks'
    - step: server-verdict
      description: On the server, look up the telemetry_id and read the verdict; treat block/challenge as a signal to require MFA, step up, or refuse.
      uses: lookup-fingerprint
    - step: tune-rules
      description: Use verdict reasons + rules endpoints to allow-list trusted devices or block known abuse patterns.
      uses: set-rule