Akamai API Security Shared resources: Rate policies API

openapi: 3.2.0
info:
  description: 'Manage your configurations for Kona Site Defender,

    Web Application Protector, and Client Reputation.

    '
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: 'Akamai: Application Security Activation history Shared resources: Rate policies API'
  version: v1
servers:
- url: https://{hostname}/appsec/v1
tags:
- description: Manage rate policies for security configurations.
  name: 'Shared resources: Rate policies'
paths:
  /configs/{configId}/versions/{versionNumber}/rate-policies:
    parameters:
    - description: A unique identifier for each configuration.
      example: '{{configId}}'
      in: path
      name: configId
      required: true
      schema:
        example: 77653
        format: int64
        type: integer
      x-akamai:
        file-path: parameters/config-id-path.yaml
    - description: A unique identifier for each version of a configuration.
      example: '{{versionNumber}}'
      in: path
      name: versionNumber
      required: true
      schema:
        example: 25
        type: integer
      x-akamai:
        file-path: parameters/version-number-path.yaml
    x-akamai:
      file-path: paths/config-rate-policies.yaml
      path-info: /configs/{configId}/versions/{versionNumber}/rate-policies
    post:
      description: Create a new rate policy for a specific configuration version. Now you can match on defined or undefined resources. If you're setting a match for either resource type, both `definedResources` and `undefinedResources` must be present in the request object or the request is considered incomplete. When `true`, match on _any_ defined resources without passing a `resourceId`. When `false`, you'll need to pass a `resourceId`. If you pass `definedResources` and `undefinedResources` with empty values, they default to `false`. You can omit both resources and use this operation without these new match criteria. Contact your account team if you'd like to match on `definedResources` or `undefinedResources`. _Products:_ All.
      externalDocs:
        description: See documentation for this operation in Akamai's Application Security API
        url: https://techdocs.akamai.com/application-security/reference/post-rate-policies
      operationId: post-rate-policies
      parameters:
      - description: For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).
        example: '{{accountSwitchKey}}'
        in: query
        name: accountSwitchKey
        required: false
        schema:
          example: 1-5C0YLB:1-8BYUX
          type: string
      requestBody:
        content:
          application/json:
            example:
              additionalMatchOptions:
              - positiveMatch: true
                type: IpAddressCondition
                values:
                - 192.0.2.210
              - positiveMatch: true
                type: RequestMethodCondition
                values:
                - GET
              averageThreshold: 5
              burstThreshold: 10
              burstWindow: 3
              clientIdentifier: ip
              condition:
                atomicConditions:
                - className: TlsFingerprintCondition
                  positiveMatch: true
                  value:
                  - a797dc449ef113be
                  - ba51ec8d71259a5b3c92d8787370e2c3
                - className: ClientReputationCondition
                  name:
                  - DOSATCK
                  - WEBATCK
                  positiveMatch: true
                  sharedIpHandling: BOTH
                  value: 3
                - className: RequestHeaderCondition
                  name:
                  - Accept
                  - Content-Type
                  nameWildcard: true
                  positiveMatch: true
                  value:
                  - json
                  - xml
                  valueCase: false
                  valueWildcard: true
                positiveMatch: true
              counterType: per_edge
              description: AFW Test Extensions
              evaluation:
                averageThreshold: 5
                burstThreshold: 8
              fileExtensions:
                positiveMatch: false
                values:
                - 3g2
                - 3gp
                - aif
                - aiff
                - au
                - avi
                - bin
                - bmp
                - cab
              hosts:
                positiveMatch: false
                values:
                - www.myexamplehostname.org
              matchType: path
              name: Test_Paths 2
              path:
                positiveMatch: true
                values:
                - /login/
                - /path/
              pathMatchType: Custom
              pathUriPositiveMatch: true
              queryParameters:
              - name: productId
                positiveMatch: true
                valueInRange: false
                values:
                - BUB_12
                - SUSH_11
              requestType: ClientRequest
              sameActionOnIpv6: false
              type: WAF
              useXForwardForHeaders: true
            schema:
              additionalProperties: false
              description: Contains details about a rate policy.
              properties:
                additionalMatchOptions:
                  description: The list of additional match conditions.
                  items:
                    additionalProperties: false
                    properties:
                      positiveMatch:
                        description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                        type: boolean
                      type:
                        description: The match condition type. The `RequestHeaderCondition` listed here is deprecated. Specify `RequestHeaderCondition` as an `atomicCondition` to match on request headers. See [Export match condition type values](https://techdocs.akamai.com/application-security/reference/cndval).
                        enum:
                        - IpAddressCondition
                        - NetworkListCondition
                        - RequestHeaderCondition
                        - RequestMethodCondition
                        - ResponseHeaderCondition
                        - ResponseStatusCondition
                        - UserAgentCondition
                        - AsNumberCondition
                        type: string
                      values:
                        description: The list of values that trigger the condition on match.
                        items:
                          type: string
                        type: array
                    required:
                    - type
                    - positiveMatch
                    - values
                    type: object
                  type: array
                apiSelectors:
                  description: The API endpoints to match in incoming requests. This only applies to the `api` `matchType`.
                  items:
                    additionalProperties: false
                    properties:
                      apiDefinitionId:
                        description: Uniquely identifies each API endpoint.
                        type: integer
                      definedResources:
                        description: When `true`, match on any resource explicitly added to your API definition without including a `resourceId`. When `false`, you'll need to pass a `resourceId`.
                        type: boolean
                      resourceIds:
                        description: The unique identifiers of the endpoint's resources.
                        items:
                          type: integer
                        type: array
                      undefinedResources:
                        description: When `true`, match on any resource you have not explicitly added to your API definition without including a `resourceId`.  When `false`, you'll need to pass a `resourceId`.
                        type: boolean
                    required:
                    - apiDefinitionId
                    type: object
                  type: array
                averageThreshold:
                  description: The allowed hits per second during any two-minute interval.
                  example: '{{averageThreshold}}'
                  minimum: 1
                  type: integer
                bodyParameters:
                  description: The list of body parameters to match on.
                  items:
                    additionalProperties: false
                    properties:
                      name:
                        description: The name you assign to a body parameter.
                        type: string
                      positiveMatch:
                        description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                        type: boolean
                      valueInRange:
                        description: Whether to match a value inside or outside a range. The range format is `min:max` — for example, `2:4`.
                        type: boolean
                      values:
                        description: The body parameter values.
                        items:
                          type: string
                        type: array
                    required:
                    - name
                    - values
                    - positiveMatch
                    type: object
                  type: array
                burstThreshold:
                  description: The allowed hits per second during any five-second interval.
                  example: '{{burstThreshold}}'
                  minimum: 1
                  type: integer
                burstWindow:
                  description: The time span for the `burstThreshold` interval. For existing rate policies, analyze your traffic in Alert mode before you reduce the measure window from 5 seconds. [Learn more about thresholds here](https://techdocs.akamai.com/kona-site-defender/docs/rate-thresholds).
                  example: '{{burstWindow}}'
                  maximum: 5
                  minimum: 1
                  type: integer
                clientIdentifier:
                  description: The client identifier you want to use to identify and track request senders. The value is required only for WAF type, and `api-key` is supported only for API match criteria. Using `ip-useragent` is typically more specific than using `ip` alone when trying to identify a client. Tracking by `cookie:value` applies to requests per individual session, even if the IP address changes.
                  enum:
                  - api-key
                  - ip-useragent
                  - ip
                  - cookie:value
                  example: '{{clientIdentifier}}'
                  type: string
                condition:
                  additionalProperties: false
                  description: Contains information about the criteria that trigger the rate policy.
                  properties:
                    atomicConditions:
                      description: The conditions that trigger the rate policy. Specify one or more request headers, TLS fingerprints, or client reputation categories.
                      items:
                        oneOf:
                        - additionalProperties: false
                          description: Collects data needed for condition matches on request headers.
                          properties:
                            className:
                              description: The type of condition. The `RequestHeaderCondition` type checks for a header from the requesting client and determines if it matches a provided header. This subtype supports the `?` wildcard to match any single character and the `*` wildcard to match any sequence of 0 or more characters. You can also match on case sensitivity.
                              enum:
                              - RequestHeaderCondition
                              type: string
                            name:
                              description: A header name. Use `name` to check whether the specified header exists.
                              items:
                                minLength: 1
                                type: string
                              minItems: 1
                              type: array
                              uniqueItems: true
                            nameWildcard:
                              description: Whether to interpret `?` and `*` as wildcards.
                              type: boolean
                            positiveMatch:
                              description: Whether the condition triggers on a match or lack of match.
                              type: boolean
                            value:
                              description: A list of unique header values. Use both `value` and `name` to check whether the requesting client’s header matches a provided header.
                              items:
                                minLength: 1
                                type: string
                              type:
                              - array
                              - 'null'
                              uniqueItems: true
                            valueCase:
                              description: Whether to consider the case sensitivity of the provided header values.
                              type: boolean
                            valueWildcard:
                              description: Whether to interpret `?` and `*` as wildcards.
                              type: boolean
                          required:
                          - className
                          - name
                          title: RequestHeaderCondition
                          type: object
                          x-akamai:
                            file-path: schemas/request-header-condition-2.yaml
                        - additionalProperties: false
                          description: Collects data needed for condition matches on TLS fingerprints.
                          properties:
                            className:
                              description: The type of condition. In this case, `TlsFingerprintCondition`.
                              enum:
                              - TlsFingerprintCondition
                              type: string
                            positiveMatch:
                              description: Whether the condition triggers on a match or lack of match.
                              type: boolean
                            value:
                              description: A list of unique TLS fingerprints.
                              items:
                                minLength: 1
                                type: string
                              minItems: 1
                              type: array
                              uniqueItems: true
                          required:
                          - className
                          - value
                          title: TlsFingerprintCondition
                          type: object
                          x-akamai:
                            file-path: schemas/tls-fingerprint-condition.yaml
                        - additionalProperties: false
                          description: Collects data needed for condition matches on Client Reputation.
                          properties:
                            className:
                              description: The type of condition. In this case, `ClientReputationCondition`.
                              enum:
                              - ClientReputationCondition
                              type: string
                            name:
                              description: Identifies the reputation category. Web scrapers (`WEBSCRP`) crawl sites and collect data like hotel rates, product prices, store locations, and more. DoS attackers (`DOSATCK`) are web clients or botnets that use automated tools to launch volumetric Denial of Service (DoS) attacks. Web attackers (`WEBATCK`) target websites and web apps with techniques like SQL injection, remote file inclusion, or cross-site scripting. Scanning tools (`SCANTL`) probe web apps for vulnerabilities during an attack's reconnaissance phase.
                              items:
                                enum:
                                - WEBSCRP
                                - DOSATCK
                                - WEBATCK
                                - SCANTL
                                type: string
                              minItems: 1
                              type: array
                              uniqueItems: true
                            positiveMatch:
                              description: Whether the condition triggers on a match or lack of match.
                              type: boolean
                            sharedIpHandling:
                              description: Identifies the IP sharing. Either `NON_SHARED`, `SHARED_ONLY`, `BOTH`.
                              enum:
                              - NON_SHARED
                              - SHARED_ONLY
                              - BOTH
                              type: string
                            value:
                              description: Threshold value that causes the trigger.
                              maximum: 10
                              minimum: 1
                              type: number
                          required:
                          - className
                          - name
                          - value
                          - sharedIpHandling
                          title: ClientReputationCondition
                          type: object
                          x-akamai:
                            file-path: schemas/client-reputation-condition.yaml
                      minItems: 1
                      type: array
                    positiveMatch:
                      description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                      type: boolean
                  type: object
                counterType:
                  default: per_edge
                  description: The rate policy counter type. Either `per_edge` for rate limiting to work per edge node, or `region_aggregated` for rate limiting to work using aggregated rate accounting across multiple edge nodes.
                  enum:
                  - per_edge
                  - region_aggregated
                  example: '{{counterType}}'
                  type: string
                createDate:
                  description: __Read-only__ The time stamp when you created the rate policy.
                  example: '{{createDate}}'
                  format: date-time
                  readOnly: true
                  type: string
                description:
                  description: Descriptive text you provide about a policy.
                  example: '{{description}}'
                  type: string
                evaluation:
                  additionalProperties: false
                  description: Contains details about rate policy evaluation.
                  properties:
                    averageThreshold:
                      description: The allowed hits per second during any two-minute interval during evaluation.
                      minimum: 1
                      type: integer
                    burstThreshold:
                      description: The allowed hits per second during any five-second interval during evaluation.
                      minimum: 1
                      type: integer
                    burstWindow:
                      description: __Read-only__ The time span for the `burstThreshold` interval used during evaluation. This value is always set to the `burstWindow` specified by the main rate policy.
                      readOnly: true
                      type: integer
                    counterType:
                      default: region_aggregated
                      description: The evaluation rate policy counter type. Either `per_edge` for rate limiting to work per edge node, or `region_aggregated` for rate limiting to work using aggregated rate accounting across multiple edge nodes.
                      enum:
                      - per_edge
                      - region_aggregated
                      type: string
                    endDate:
                      description: __Read-only__ The time stamp when evaluation ends.
                      format: date-time
                      readOnly: true
                      type: string
                    evaluationId:
                      description: __Read-only__ Uniquely identifies an evaluation.
                      readOnly: true
                      type: integer
                    evaluationStatus:
                      description: __Read-only__ Reflects evaluation status, either `in_progress`, `pending_activation`, or `completed`.
                      enum:
                      - in_progress
                      - pending_activation
                      - completed
                      readOnly: true
                      type: string
                    startDate:
                      description: __Read-only__ The time stamp when evaluation starts.
                      format: date-time
                      readOnly: true
                      type: string
                    version:
                      description: __Read-only__ Evaluation version.
                      readOnly: true
                      type: integer
                  required:
                  - averageThreshold
                  - burstThreshold
                  type: object
                fileExtensions:
                  additionalProperties: false
                  description: Contains the file extension match criteria.
                  properties:
                    positiveMatch:
                      description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                      type: boolean
                    values:
                      description: The file extensions to match on.
                      items:
                        type: string
                      type: array
                  required:
                  - positiveMatch
                  - values
                  type: object
                hostnames:
                  description: __Deprecated__. The hostnames to match. This array member is deprecated. Use the `hosts` object instead.
                  items:
                    type: string
                  type: array
                hosts:
                  additionalProperties: false
                  description: The hostnames to match, and whether to trigger on a match or absence of match.
                  properties:
                    positiveMatch:
                      default: true
                      description: When `true`, triggers on hostnames that match any hostnames in this array. When `false`, triggers on hostnames that don't match any in this array.
                      type: boolean
                    values:
                      description: The hostnames you choose to match, or specifically not match.
                      items:
                        type: string
                      type: array
                  required:
                  - positiveMatch
                  - values
                  type: object
                id:
                  description: __Read-only__ Uniquely identifies each rate policy.
                  example: '{{id}}'
                  readOnly: true
                  type: integer
                matchType:
                  description: The match type in a rate policy. Either `path` to match website paths or `api` to match API paths.
                  enum:
                  - path
                  - api
                  example: '{{matchType}}'
                  type: string
                name:
                  description: The name you assign to a rate policy.
                  example: '{{name}}'
                  type: string
                path:
                  additionalProperties: false
                  description: Contains details about the path match criteria.
                  properties:
                    positiveMatch:
                      description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                      type: boolean
                    values:
                      description: The list of paths to match on.
                      items:
                        type: string
                      type: array
                  required:
                  - positiveMatch
                  - values
                  type: object
                pathMatchType:
                  description: The type of paths to match in incoming requests. Either `AllRequests` to match an empty path or any path that ends in a trailing slash (`/`), `TopLevel` to match top-level hostnames only, or `Custom` to match a specific path or path component. This applies only when the corresponding `matchType` member is `path`.
                  enum:
                  - AllRequests
                  - TopLevel
                  - Custom
                  example: '{{pathMatchType}}'
                  type: string
                pathUriPositiveMatch:
                  description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                  example: '{{pathUriPositiveMatch}}'
                  type: boolean
                queryParameters:
                  description: The list of query parameter objects to match on.
                  items:
                    additionalProperties: false
                    properties:
                      name:
                        description: The query parameter name.
                        type: string
                      positiveMatch:
                        description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
                        type: boolean
                      valueInRange:
                        description: Whether to match a value inside or outside a range. The range format is `min:max` — for example, `2:4`.
                        type: boolean
                      values:
                        description: The list of query parameter values.
                        items:
                          type: string
                        type: array
                    required:
                    - name
                    - values
                    - positiveMatch
                    type: object
                  type: array
                requestType:
                  description: The type of requests to count towards the rate policy's thresholds. Either `ClientRequest` to count client requests to edge servers, `ClientResponse` to count edge responses to the client, `ForwardResponse` to count origin responses to the client, or `ForwardRequest` to count edge requests to your origin.
                  enum:
                  - ClientRequest
                  - ClientResponse
                  - ForwardResponse
                  - ForwardRequest
                  example: '{{requestType}}'
                  type: string
                sameActionOnIpv6:
                  description: Whether to apply the same action to the IPv6 traffic as to the IPv4 traffic.
                  example: '{{sameActionOnIpv6}}'
                  type: boolean
                type:
                  description: The rate policy type. Either `WAF` for Web Application Firewall, or `BOTMAN` for Bot Manager.
                  enum:
                  - WAF
                  - BOTMAN
                  example: '{{type}}'
                  type: string
                updateDate:
                  description: __Read-only__ The ISO 8601 timestamp when you last updated the rate policy.
                  example: '{{updateDate}}'
                  format: date-time
                  readOnly: true
                  type: string
                useXForwardForHeaders:
                  description: Whether to check the contents of the `X-Forwarded-For` header in incoming requests.
                  example: '{{useXForwardForHeaders}}'
                  type: boolean
                used:
                  description: __Read-only__ Whether you're currently using the rate policy.
                  example: '{{used}}'
                  readOnly: true
                  type: boolean
              required:
              - matchType
              - type
              - name
              - averageThreshold
              - burstThreshold
              - clientIdentifier
              - requestType
              - sameActionOnIpv6
              - pathMatchType
              type: object
              x-akamai:
                file-path: schemas/rate-policy.yaml
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                additionalMatchOptions:
                - positiveMatch: true
                  type: IpAddressCondition
                  values:
                  - 192.0.2.13
                - positiveMatch: true
                  type: RequestMethodCondition
                  values:
                  - GET
                averageThreshold: 5
                burstThreshold: 10
                burstWindow: 3
                clientIdentifier: ip
                condition:
                  atomicConditions:
                  - className: TlsFingerprintCondition
                    positiveMatch: true
                    value:
                    - a797dc449ef113be
                    - ba51ec8d71259a5b3c92d8787370e2c3
                  - className: ClientReputationCondition
                    name:
                    - DOSATCK
                    - WEBATCK
                    positiveMatch: true
                    sharedIpHandling: BOTH
                    value: 3
                  - className: RequestHeaderCondition
                    name:
                    - Accept
                    - Content-Type
                    nameWildcard: true
                    positiveMatch: true
                    value:
                    - json
                    - xml
                    valueCase: false
                    valueWildcard: true
                  positiveMatch: true
                counterType: per_edge
                createDate: '2016-07-22 18:57:08.0'
                description: AFW Test Extensions
                evaluation:
                  averageThreshold: 5
                  burstThreshold: 8
                  burstWindow: 5
                  counterType: region_aggregated
                  endDate: '2024-04-11T16:04:43Z'
                  evaluationId: 97
                  evaluationStatus: in_progress
                  startDate: '2024-03-28T16:04:43Z'
                  version: 1
                fileExtensions:
                  positiveMatch: false
                  values:
                  - 3g2
                  - 3gp
                  - aif
                  - aiff
                  - au
                  - avi
                  - bin
                  - bmp
                  - cab
                hosts:
                  positiveMatch: false
                  values:
                  - www.myexamplehostname.org
                id: 484616
                matchType: path
                name: Test_Paths 2
                path:
                  positiveMatch: true
                  values:
                  - /login/
                  - /path/
                pathMatchType: Custom
                pathUriPositiveMatch: true
                queryParamet

# --- truncated at 32 KB (241 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/akamai-api-security/refs/heads/main/openapi/akamai-api-security-shared-resources-rate-policies-api-openapi.yml