openapi: 3.0.2
info:
  title: Rules
  version: ''
  description: >-
    Rules APIs provided by Fraud Prevention are used to fine-tune Fraud
    Prevention decisions.
servers:
  - url: https://api.sbx.transmitsecurity.io/risk/v1
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/risk/v1
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/risk/v1
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/risk/v1
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/risk/v1
    description: Production environment (AU)
paths:
  /rules:
    post:
      summary: Create rule
      description: >-
        Creates a new recommendation rule. Returns the `rule_id` used to
        reference the rule in subsequent requests, along with the rule data.
      operationId: createRule
      security:
        - risk_access_token: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rule_request'
      responses:
        '201':
          $ref: '#/components/responses/success_create_rule'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          $ref: '#/components/responses/collision'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
    get:
      summary: Get all rules
      description: Retrieves a list of all recommendation rules
      operationId: getRules
      security:
        - risk_access_token: []
      responses:
        '200':
          $ref: '#/components/responses/success_get_rules'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
  /rules/{rule_id}:
    get:
      summary: Get rule by ID
      description: Retrieves a specific recommendation rule by its ID
      operationId: getRuleById
      security:
        - risk_access_token: []
      parameters:
        - name: rule_id
          description: ID of the recommendation rule
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/success_get_rule_by_id'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
    put:
      summary: Update rule by ID
      description: Updates a specific recommendation rule
      operationId: updateRule
      security:
        - risk_access_token: []
      parameters:
        - name: rule_id
          description: ID of the recommendation rule
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rule_request'
      responses:
        '200':
          $ref: '#/components/responses/success_update_rule'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
    delete:
      summary: Delete rule by ID
      description: >-
        Deletes a specific recommendation rule. Note that you can also disable
        rules if needed using the enabled rule attribute.
      operationId: deleteRule
      security:
        - risk_access_token: []
      parameters:
        - name: rule_id
          description: ID of the recommendation rule
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/success_delete_rule'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
components:
  schemas:
    rule_request:
      type: object
      description: Recommendation rule
      required:
        - priority
        - recommendation
        - mode
        - type
        - matchers
      properties:
        name:
          $ref: '#/components/schemas/rule_name'
        priority:
          $ref: '#/components/schemas/rule_priority'
        recommendation:
          $ref: '#/components/schemas/rule_recommendation_type'
        enabled:
          $ref: '#/components/schemas/rule_enabled'
        mode:
          $ref: '#/components/schemas/rule_mode'
        type:
          $ref: '#/components/schemas/rule_type'
        description:
          $ref: '#/components/schemas/rule_description'
        matchers:
          $ref: '#/components/schemas/matchers'
    rule_response:
      allOf:
        - type: object
          properties:
            id:
              $ref: '#/components/schemas/rule_id'
        - $ref: '#/components/schemas/rule_request'
        - $ref: '#/components/schemas/rules_dates'
    rules_dates:
      type: object
      properties:
        created_date:
          type: string
          description: Date the rule was created
          format: date
        updated_date:
          type: string
          description: Date the rule was last updated
          format: date
    matchers:
      type: array
      description: Contains a set of activity matchers that define the rule matching logic
      items:
        $ref: '#/components/schemas/matcher_info'
    matcher_info:
      type: object
      description: Contains a set of activity matchers that define the rule matching logic
      properties:
        ip_cidrs:
          $ref: '#/components/schemas/ip_cidrs_matcher'
        device_ids:
          $ref: '#/components/schemas/device_ids_matcher'
        device_fingerprints:
          $ref: '#/components/schemas/device_fingerprints_matcher'
        device_public_keys:
          $ref: '#/components/schemas/device_public_keys_matcher'
        user_ids:
          $ref: '#/components/schemas/user_ids_matcher'
        country_codes:
          $ref: '#/components/schemas/country_codes_matcher'
        browser_names:
          $ref: '#/components/schemas/browser_names_matcher'
        os_versions:
          $ref: '#/components/schemas/os_versions_matcher'
        action_type:
          $ref: '#/components/schemas/action_type_matcher'
        client_id:
          $ref: '#/components/schemas/client_id_matcher'
        application_id:
          $ref: '#/components/schemas/application_id_matcher'
        asn_id:
          $ref: '#/components/schemas/asn_id_matcher'
        organization_name:
          $ref: '#/components/schemas/organization_name_matcher'
        organization_type:
          $ref: '#/components/schemas/organization_type_matcher'
        ip_timezone:
          $ref: '#/components/schemas/ip_timezone_matcher'
        device_timezone:
          $ref: '#/components/schemas/device_timezone_matcher'
        device_platform:
          $ref: '#/components/schemas/device_platform_matcher'
        user_agent:
          $ref: '#/components/schemas/user_agent_matcher'
        location:
          $ref: '#/components/schemas/location_matcher'
    ip_cidrs_matcher:
      type: object
      description: Matches based on IP address
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - ip_in
            - ip_not_in
        value:
          type: array
          description: List of IP ranges in CIDR notation
          items:
            type: string
    device_ids_matcher:
      type: object
      description: Matches based on the device ID
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >-
            List of device identifiers generated by Transmit Security and stored
            by the SDK
          items:
            type: string
    device_fingerprints_matcher:
      type: object
      description: Matches based on device fingerprint
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >-
            List of device fingerprints calculated based on multiple device
            persistent identifiers
          items:
            type: string
    device_public_keys_matcher:
      type: object
      description: Matches based on device public key
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >-
            List of unique and persistent device public keys derived from
            cryptographic binding
          items:
            type: string
    user_ids_matcher:
      type: object
      description: Matches based on user identifier
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of opaque identifiers of users in your system
          items:
            type: string
    country_codes_matcher:
      type: object
      description: Matches based on the country in which the device is located
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of country codes per ISO 3166-1 alpha-2 standard
          items:
            type: string
    browser_names_matcher:
      type: object
      description: Matches based on browser name
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >
            List of browser names as presented by Transmit Security systems.
            e.g. `yandex`, `electron`
          items:
            type: string
    os_versions_matcher:
      type: object
      description: Matches based on the device OS version
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >
            List of OS versions as presented by Transmit Security systems. e.g.
            `14.4.2`, `x86_64`
          items:
            type: string
    action_type_matcher:
      type: object
      description: >-
        Matches based on the client action for which the recommendation is
        requested
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >-
            List of client actions (such as `login` or `register`). [Learn
            more](guides/risk/recommendations/#action-types)
          items:
            type: string
    client_id_matcher:
      type: object
      description: Matches based on client ID
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of client IDs
          items:
            type: string
    application_id_matcher:
      type: object
      description: Matches based on app ID
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of application IDs, used to identify Transmit applications
          items:
            type: string
    asn_id_matcher:
      type: object
      description: Matches based on the ASN detected using the IP address
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >-
            List of AS numbers detected by Transmit using IP address (e.g.,
            AS13339)
          items:
            type: string
    organization_name_matcher:
      type: object
      description: Matches based on the organization name associated with the IP address
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of organization names
          items:
            type: string
    organization_type_matcher:
      type: object
      description: Matches based on the organization type associated with the IP address
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of organization types
          items:
            type: string
    ip_timezone_matcher:
      type: object
      description: Matches based on the timezone detected by Transmit using IP address
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of TZ identifiers (e.g., America/New_York, Asia/Tokyo, UTC)
          items:
            type: string
    device_timezone_matcher:
      type: object
      description: >-
        Matches based on the timezone detected by Transmit using device
        telemetry
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: List of TZ identifiers (e.g., America/New_York , Asia/Tokyo, UTC)
          items:
            type: string
    device_platform_matcher:
      type: object
      description: >-
        Matches based on device type, as classified by Transmit (e.g., desktop,
        mobile, wearable)
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - in
            - not_in
        value:
          type: array
          description: >-
            List of device types, as classified by Transmit (e.g., desktop ,
            mobile, wearable)
          items:
            type: string
    user_agent_matcher:
      type: object
      description: Matches based on user agent
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - contains
            - not_contains
        value:
          type: array
          description: List of user agents
          items:
            type: string
    location_matcher:
      type: object
      description: >-
        Matches based on the place in the application in which the action was
        performed (such as page URL)
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Matcher operation
          enum:
            - contains
            - not_contains
        value:
          type: array
          description: List of locations (e.g., page URLs)
          items:
            type: string
    rule_recommendation_type:
      type: string
      description: Recommendation type
      enum:
        - challenge
        - deny
        - trust
        - allow
    rule_name:
      type: string
      example: Block risky countries
      description: >
        Name of the recommendation rule. Must be unique across the tenant.
        Autogenerated if not provided.
    rule_priority:
      type: integer
      example: 10
      minimum: 1
      maximum: 1000
      description: >
        Priority of the recommendation rule, which determines the order in which
        rules are evaluated. Rules are evaluated from smallest to biggest
        priority value and only the first rule to match will apply. Priority
        value must be unique.
    rule_enabled:
      type: boolean
      default: false
      description: Whether or not the rule will be evaluated.
    rule_mode:
      type: string
      description: >
        Allows you to simulate a rule and evaluate its impact before releasing
        it to production. The simulation occurs each time a recommendation is
        requested. If a preview rule matches the request (meaning, its priority
        is higher than all matching rules), the response will include this
        preview rule and what the recommendation would have been if all rules
        were in production.
      enum:
        - preview
        - production
    rule_type:
      type: string
      description: Default type, must be "risk"
      enum:
        - risk
    rule_description:
      type: string
      description: Description for the rule
    rule_id:
      type: string
      description: ID of the recommendation rule, used to reference the rule
      format: uuid
    create_rule_response:
      type: object
      properties:
        message:
          type: string
        rule_id:
          $ref: '#/components/schemas/rule_id'
        data:
          $ref: '#/components/schemas/rule_response'
    get_all_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/rule_response'
    get_rule_response:
      type: object
      properties:
        id:
          type: string
          description: Rule ID
        data:
          $ref: '#/components/schemas/rule_response'
    update_rule_response:
      type: object
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/rule_response'
    delete_rule_response:
      type: object
      properties:
        message:
          type: string
  responses:
    success_create_rule:
      description: Rules created and stored successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/create_rule_response'
    success_get_rules:
      description: Rules retrieved successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/get_all_response'
    success_get_rule_by_id:
      description: Rule retrieved successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/get_rule_response'
    success_update_rule:
      description: Rule updated successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/update_rule_response'
    success_delete_rule:
      description: Rule updated successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/delete_rule_response'
    unauthorized:
      description: Invalid authentication
    forbidden:
      description: Invalid authorization (e.g, unauthorized resource)
    rate_limit_reached:
      description: Rate limit reached
    internal_error:
      description: Internal error
    collision:
      description: Unique field collision
    bad_request:
      description: Bad request
    not_found:
      description: Not found
  securitySchemes:
    risk_access_token:
      type: http
      scheme: bearer
      description: >-
        An access token generated by the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken), which should
        target the following resource: `https://risk.identity.security`
      bearerFormat: JWT
