Arkose Labs Verify API

openapi: 3.1.0
info:
  title: Arkose Labs Edge Verify API
  version: v1
  description: Lightweight server-side detection API. The customer relays the inbound client HTTP request (method, url, headers, body) to Arkose Edge, which returns a risk assessment and allow/deny recommendation from consortium intelligence — for surfaces where client-side JavaScript/SDK cannot run (mobile backends, IoT, programmatic APIs). Generated by API Evangelist from the published Arkose Labs Edge API documentation.
  contact:
    name: Arkose Labs Support
    url: https://www.arkoselabs.com/support/
  x-apievangelist-method: generated
  x-apievangelist-source: https://developer.arkoselabs.com/docs/edge-api-request-parameters
servers:
- url: https://client-api.arkoselabs.com
  description: Arkose Edge API host
tags:
- name: Verify
  description: Session verification
paths:
  /api/v4/verify/:
    post:
      operationId: verifySession
      summary: Verify an Arkose Labs session
      description: Validate a session token returned by the client-side API. Always call server-side. Do NOT fail-open on HTTP 400; fail-open is acceptable on 5xx with exponential backoff.
      tags:
      - Verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      responses:
        '200':
          description: Verification result (simple 1/0 integer when simple_mode, else full JSON assessment; error object on token problems).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          description: Bad request (malformed body / invalid parameters). Do not fail-open.
        '500':
          description: Server error. Fail-open with exponential backoff is acceptable.
components:
  schemas:
    VerifyResponse:
      oneOf:
      - description: error response
        properties:
          error:
            type: string
          verified:
            format: date-time
            type: string
        required:
        - error
        - verified
        type: object
      - default: 0
        description: simple mode
        type: integer
      - properties:
          agent_trust:
            properties:
              agent:
                oneOf:
                - additionalProperties: false
                  description: Agent metadata when available; present only when detected is true
                  properties:
                    name:
                      description: Name of the detected agent trust agent
                      type: string
                  required:
                  - name
                  type: object
                - type: 'null'
              detected:
                default: false
                description: Whether the session was classified as an agent trust client
                type: boolean
              web_bot_auth:
                oneOf:
                - additionalProperties: false
                  description: 'Outcome of RFC 9421 Web-Bot-Auth header verification captured at setup-session. Independent signal from detected/agent: a verified web_bot_auth payload with detected=false is valid (cryptographic proof of identity without matching the heuristic allowlist)'
                  properties:
                    agent:
                      oneOf:
                      - default: null
                        description: Bare URI of the bot operator's JWKS directory origin
                        type: string
                      - type: 'null'
                    key_id:
                      oneOf:
                      - default: null
                        description: RFC 7638 thumbprint of the signing key
                        type: string
                      - type: 'null'
                    provided:
                      default: false
                      description: Whether WBA headers were present on the setup-session request
                      type: boolean
                    signature_fail_reason:
                      oneOf:
                      - default: null
                        description: Reason verification failed; null on success
                        enum:
                        - bad_signature
                        - missing_key
                        - directory_unreachable
                        - malformed_input
                        - signature_expired
                        - unsupported_profile
                        - null
                        type: string
                      - type: 'null'
                    signature_verified:
                      default: false
                      description: Whether the RFC 9421 signature cryptographically verified
                      type: boolean
                  required:
                  - provided
                  - agent
                  - key_id
                  - signature_verified
                  - signature_fail_reason
                  type: object
                - type: 'null'
            required:
            - detected
            type: object
          aggregations:
            properties:
              error:
                oneOf:
                - description: Error message if aggregations have failed or are incomplete
                  type: string
                - type: 'null'
              ip:
                description: IP-based aggregation data
                properties:
                  long_term:
                    properties:
                      count:
                        oneOf:
                        - type: integer
                        - type: 'null'
                      interval_minutes:
                        oneOf:
                        - type: integer
                        - type: 'null'
                      threshold:
                        oneOf:
                        - type: integer
                        - type: 'null'
                    type: object
                  short_term:
                    properties:
                      count:
                        oneOf:
                        - type: integer
                        - type: 'null'
                      interval_minutes:
                        oneOf:
                        - type: integer
                        - type: 'null'
                      threshold:
                        oneOf:
                        - type: integer
                        - type: 'null'
                    type: object
                type: object
            type: object
          data_exchange:
            properties:
              blob_decrypted:
                default: null
                oneOf:
                - description: Indicates if the customer provided DataExchange blob was successfully decrypted. If no blob was received; or DataExchange is not enabled for your key it will be null
                  type: boolean
                - type: 'null'
              blob_received:
                default: null
                oneOf:
                - description: Indicates whether the customer request included a DataExchange blob. If this feature is not enabled for your key; it will be null
                  type: boolean
                - type: 'null'
            type: object
          device_id:
            properties:
              arkose_id:
                description: Composite key of stateful & stateless id
                type: string
              confidence_score:
                description: Confidence of the uniqueness of the arkose id
                type: number
              device_first_seen:
                description: When the device was first seen
                type: string
              device_last_seen:
                description: When the device was last seen
                type: string
              device_spoofing_detected:
                description: Whether the current user has been detected spoofing their device
                type: boolean
              risk_band:
                description: Risk band of the device
                type: string
              risk_insights:
                description: Risk insights of the device
                items:
                  type: string
                type: array
              risk_score:
                description: Risk score of the device
                type: number
              stateful_challenge_bypassed:
                description: Whether the current challenge was bypassed
                type: boolean
              stateful_challenges_bypassed:
                description: Number of challenges the user has been allowed to bypass since their last solve
                type: integer
              stateful_change_reasons:
                description: Reasons why a challenge may have been presented
                items:
                  type: string
                type: array
              stateful_device_id:
                description: The Stateful Device ID attributed to this user
                type: string
              stateless_device_id:
                description: The current device ID
                type: string
              stateless_device_id_previous:
                description: Previous Stateless Device ID
                type: string
              stateless_device_id_previous_version:
                description: Version of the previous Stateless Device ID
                type: string
              stateless_device_id_version:
                description: Version of the Stateless Device ID
                type: string
            type: object
          email_intelligence:
            properties:
              deenumerated_email_unique_counts:
                properties:
                  error:
                    description: Error message if counts could not be retrieved for the aggregation
                    type: string
                  long_term_count:
                    description: Numeric count of the aggregation metric in long term
                    type: integer
                  long_term_period_minutes:
                    description: The time period over which the long term count was aggregated in minutes
                    type: integer
                  short_term_count:
                    default: 0
                    description: Numeric count of the aggregation metric in short term
                    type: integer
                  short_term_period_minutes:
                    default: 0
                    description: The time period over which the short term count was aggregated in minutes
                    type: integer
                required:
                - short_term_count
                - short_term_period_minutes
                type: object
              detumbled_email_instance_counts:
                properties:
                  error:
                    description: Error message if counts could not be retrieved for the aggregation
                    type: string
                  long_term_count:
                    description: Numeric count of the aggregation metric in long term
                    type: integer
                  long_term_period_minutes:
                    description: The time period over which the long term count was aggregated in minutes
                    type: integer
                  short_term_count:
                    default: 0
                    description: Numeric count of the aggregation metric in short term
                    type: integer
                  short_term_period_minutes:
                    default: 0
                    description: The time period over which the short term count was aggregated in minutes
                    type: integer
                required:
                - short_term_count
                - short_term_period_minutes
                type: object
              detumbled_email_stats:
                properties:
                  handle_dvorak_typing_distance:
                    default: 0
                    type: number
                  handle_length:
                    default: 0
                    type: integer
                  handle_num_alpha_chars:
                    default: 0
                    type: integer
                  handle_num_consonants:
                    default: 0
                    type: integer
                  handle_num_numeric_chars:
                    default: 0
                    type: integer
                  handle_num_special_chars:
                    default: 0
                    type: integer
                  handle_num_vowels:
                    default: 0
                    type: integer
                  handle_qwerty_typing_distance:
                    default: 0
                    type: number
                type: object
              detumbled_email_unique_counts:
                properties:
                  error:
                    description: Error message if counts could not be retrieved for the aggregation
                    type: string
                  long_term_count:
                    description: Numeric count of the aggregation metric in long term
                    type: integer
                  long_term_period_minutes:
                    description: The time period over which the long term count was aggregated in minutes
                    type: integer
                  short_term_count:
                    default: 0
                    description: Numeric count of the aggregation metric in short term
                    type: integer
                  short_term_period_minutes:
                    default: 0
                    description: The time period over which the short term count was aggregated in minutes
                    type: integer
                required:
                - short_term_count
                - short_term_period_minutes
                type: object
              domain_instance_counts:
                properties:
                  error:
                    description: Error message if counts could not be retrieved for the aggregation
                    type: string
                  long_term_count:
                    description: Numeric count of the aggregation metric in long term
                    type: integer
                  long_term_period_minutes:
                    description: The time period over which the long term count was aggregated in minutes
                    type: integer
                  short_term_count:
                    default: 0
                    description: Numeric count of the aggregation metric in short term
                    type: integer
                  short_term_period_minutes:
                    default: 0
                    description: The time period over which the short term count was aggregated in minutes
                    type: integer
                required:
                - short_term_count
                - short_term_period_minutes
                type: object
              domain_stats:
                properties:
                  domain_dvorak_typing_distance:
                    type: number
                  domain_length:
                    type: integer
                  domain_max_consec_consonants:
                    type: integer
                  domain_max_consec_vowels:
                    type: integer
                  domain_num_alpha_chars:
                    type: integer
                  domain_num_consonants:
                    type: integer
                  domain_num_numeric_chars:
                    type: integer
                  domain_num_special_chars:
                    type: integer
                  domain_num_vowels:
                    type: integer
                  domain_qwerty_typing_distance:
                    type: number
                type: object
              email_assessment:
                properties:
                  anomalous_handle_composition:
                    default: false
                    type: boolean
                  deenumerated_domain_length:
                    type: integer
                  deenumerated_email_address:
                    default: ''
                    type: string
                  deenumerated_email_handle_length:
                    default: 0
                    type: integer
                  detumbled_email_address:
                    default: ''
                    type: string
                  detumbled_email_first_seen:
                    default: ''
                    type: string
                  detumbled_email_first_seen_in_days:
                    default: 0
                    type: integer
                  domain_enrichment:
                    properties:
                      domain_age:
                        oneOf:
                        - description: Number of days since the domain was registered (i.e. age of the domain in whole days). Null when domain intelligence data is unavailable for the domain.
                          type: integer
                        - type: 'null'
                      domain_creation_date:
                        oneOf:
                        - default: null
                          description: The date that the email's domain was registered
                          type: string
                        - type: 'null'
                      domain_name_servers:
                        oneOf:
                        - default: null
                          items:
                            type: string
                          type: array
                        - type: 'null'
                      domain_org:
                        default: ''
                        type: string
                      domain_registration_country:
                        default: ''
                        type: string
                      error:
                        type: string
                      is_disposable:
                        default: false
                        type: boolean
                      is_domain_missing:
                        default: false
                        type: boolean
                    type: object
                  domain_metric_entropy:
                    type: number
                  domain_relative_usage_factor:
                    default: 0
                    type: number
                  domain_shannon_entropy:
                    type: number
                  email_address:
                    default: ''
                    type: string
                  email_domain:
                    default: ''
                    type: string
                  email_handle_length:
                    default: 0
                    type: integer
                  email_risk_score:
                    default: 0
                    type: number
                  is_enumerated_email:
                    default: false
                    type: boolean
                  is_invalid_email:
                    default: false
                    type: boolean
                  is_mx_record_present:
                    default: false
                    type: boolean
                  is_mx_valid:
                    default: false
                    type: boolean
                  is_private_relay:
                    default: false
                    type: boolean
                  is_role_email:
                    default: false
                    type: boolean
                  is_suspicious_email_handle:
                    default: false
                    type: boolean
                  is_tumbled_email:
                    default: false
                    type: boolean
                  suggested_action:
                    default: ''
                    type: string
                type: object
              error:
                type: string
              total_email_counts:
                properties:
                  error:
                    description: Error message if counts could not be retrieved for the aggregation
                    type: string
                  long_term_count:
                    description: Numeric count of the aggregation metric in long term
                    type: integer
                  long_term_period_minutes:
                    description: The time period over which the long term count was aggregated in minutes
                    type: integer
                  short_term_count:
                    default: 0
                    description: Numeric count of the aggregation metric in short term
                    type: integer
                  short_term_period_minutes:
                    default: 0
                    description: The time period over which the short term count was aggregated in minutes
                    type: integer
                required:
                - short_term_count
                - short_term_period_minutes
                type: object
            required:
            - total_email_counts
            type: object
          fingerprint:
            properties:
              browser_characteristics:
                properties:
                  browser_name:
                    oneOf:
                    - default: null
                      description: Name of the browser used
                      type: string
                    - type: 'null'
                  browser_version:
                    oneOf:
                    - default: null
                      description: Version of the browser used
                      type: string
                    - type: 'null'
                  canvas_fingerprint:
                    default: null
                    oneOf:
                    - description: Canvas fingerprint value
                      type: integer
                    - type: 'null'
                  color_depth:
                    default: null
                    oneOf:
                    - description: Color depth of the browser in bits per pixel
                      type: integer
                    - type: 'null'
                  indexed_database:
                    default: false
                    description: Whether indexed database is available in the browser
                    type: boolean
                  session_storage:
                    default: false
                    description: Whether session storage is available in the browser
                    type: boolean
                required:
                - browser_name
                - browser_version
                - color_depth
                - session_storage
                - indexed_database
                - canvas_fingerprint
                type: object
              device_characteristics:
                properties:
                  behavior:
                    default: false
                    description: Information about device behavior
                    type: boolean
                  cpu_class:
                    oneOf:
                    - default: null
                      description: CPU class of the device
                      examples:
                      - x86
                      - ARM
                      type: string
                    - type: 'null'
                  hardware_concurrency:
                    default: null
                    oneOf:
                    - description: Number of logical processors available to run threads on the device
                      type: integer
                    - type: 'null'
                  ja4_hash:
                    oneOf:
                    - default: null
                      description: JA4 TLS fingerprint hash
                      type: string
                    - type: 'null'
                  max_resolution_supported:
                    default: null
                    oneOf:
                    - default: null
                      description: Maximum resolution supported by the device [width
                      items:
                        type: integer
                      type: array
                    - type: 'null'
                  operating_system:
                    oneOf:
                    - default: null
                      description: Name of the operating system
                      examples:
                      - Windows
                      - OS X
                      type: string
                    - type: 'null'
                  operating_system_version:
                    oneOf:
                    - default: null
                      description: Version of the operating system
                      examples:
                      - '10'
                      - Mojave
                      type: string
                    - type: 'null'
                  platform:
                    oneOf:
                    - default: null
                      description: Platform of the device
                      examples:
                      - MacIntel
                      - Win32
                      type: string
                    - type: 'null'
                  screen_resolution:
                    default: null
                    oneOf:
                    - default: null
                      description: Screen resolution in pixels [width
                      items:
                        type: integer
                      type: array
                    - type: 'null'
                  touch_support:
                    default: false
                    description: Whether touch is supported on the device
                    type: boolean
                type: object
              user_preferences:
                properties:
                  timezone_offset:
                    default: null
                    oneOf:
                    - description: Timezone offset in minutes from UTC
                      examples:
                      - 1000
                      - -800
                      - 0
                      type: integer
                    - type: 'null'
                type: object
            type: object
          ip_intelligence:
            properties:
              asn:
                default: null
                oneOf:
                - description: Autonomous System Number of the IP address
                  type: integer
                - type: 'null'
              city:
                oneOf:
                - default: null
                  description: City of the IP address
                  type: string
                - type: 'null'
              connection_type:
                oneOf:
                - default: null
                  description: Type of internet connection
                  type: string
                - type: 'null'
              country:
                oneOf:
                - default: null
                  description: Country of the IP address
                  type: string
                - type: 'null'
              is_proxy:
                default: false
                description: Whether the IP is from a proxy service
                type: boolean
              is_tor:
                default: false
                description: Whether the IP is from a TOR exit node
                type: boolean
              is_vpn:
                default: false
                description: Whether the IP is from a VPN service
                type: boolean
              isp:
                oneOf:
                - default: null
                  description: Internet Service Provider associated with the IP
                  type: string
                - type: 'null'
              latitude:
                oneOf:
                - default: null
                  description: Latitude of the IP address location
                  type: string
                - type: 'null'
              longitude:
                oneOf:
                - default: null
                  description: Longitude of the IP address location
                  type: string
                - type: 'null'
              network_info_rtt:
                default: null
                oneOf:
                - description: Network round-trip time in milliseconds
                  type: integer
                - type: 'null'
              proxy_type:
                default: not a proxy
                description: Type of proxy service
                examples:
                - anonymous
                - transparent
                - corporate
                - consumer-privacy
                - public
                - edu
                - data center
                - not a proxy
                type: string
              public_access_point:
                default: false
                description: Whether the IP is from a public access point
                type: boolean
              region:
                oneOf:
                - default: null
                  description: Region/state of the IP address
                  type: string
                - type: 'null'
              timezone:
                oneOf:
                - default: null
                  description: Timezone of the IP address location
                  type: string
                - type: 'null'
              user_ip:
                default: null
                oneOf:
                - format: ipv4
                  type: string
                - format: ipv6
                  type: string
                - type: 'null'
            required:
            - user_ip
            - is_tor
            - is_vpn
            - is_proxy
            - country
            - region
            - city
            - isp
            - public_access_point
            - connection_type
            - proxy_type
            - latitude
            - longitude
            - timezone
            type: object
          mics_verdict:
            properties:
              app_check_account_check:
                type: string
              app_check_activity_level:
                type: string
              app_check_cert_check:
                type: string
              app_check_platform:
                type: string
              app_check_result:
                type: string
              app_check_risk_level:
                type: string
              app_check_timed_out:
                type: boolean
              device_check_platform:
                type: string
              device_check_result:
                type: string
              device_check_timed_out:
                type: boolean
              mics_response:
                type: string
            type: object
          proof_of_work:
            properties:
              attempted:
                default: false
                description: Indicates that user submitted an attempt at PoW
                type: boolean
              challenged:
                default: false
                description: Indicates that PoW was enabled for the session
                type: boolean
              difficulty_level:
                oneOf:
                - default: null
                  description: Indicates the difficulty level of the PoW
                  type: string
                - type: 'null'
              passed:
                default: false
                description: Indicates that PoW attempt was passed by the user
                type: boolean
              transparent:
                default: false
                description: Indicates that no UI was shown to the user
                type: boolean
            required:
            - challenged
            - attempted
            - passed
            - difficulty_level
            - transparent
            type: object
          session_details:
            properties:
              attempted:
                default: false
                description: Whether an attempt was made to solve the challenge
                type: boolean
              challenge_type:
                oneOf:
                - default: null
                  description: The type of challenge that the end-user solved
                  enum:
                  - audio
                  - transparent
                  - visual
                  - pow
                  - pow+visual
                  - pow+audio
                  - null
                  type: string
                - type: 'null'
              check_answer:
                oneOf:
                - default: null
                  description: Timestamp when the answer was checked
                  format: date-time
                  type: string
                - type: 'null'

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arkose-labs/refs/heads/main/openapi/arkose-labs-verify-api-openapi.yml