openapi: 3.0.0
info:
title: 'Akamai: API Endpoint Definition Access tokens Shared resources: Rate policies API'
version: '2'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
description: Manage rate policies for security configurations.
servers:
- url: https://{hostname}/api-definitions/v2
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.
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.
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: __All products__ 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`.
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).
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
clientIdentifiers:
- 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
penaltyBoxDuration: TEN_MINUTES
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.
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.
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).
maximum: 5
minimum: 1
type: integer
clientIdentifier:
deprecated: true
description: __Deprecated__ 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. This field will be removed in future releases. Use `clientIdentifiers` instead.
minLength: 0
type: string
x-akamai:
status: DEPRECATED
clientIdentifiers:
description: Client identifiers to 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. Specify `request-header:value` to track by a named request header, like `User-Agent`. Use `query-string:value` to track by a specific named query parameter. The `tls-fingerprint` identifier is available for traffic transmitted using secure transport (HTTPS).
items:
enum:
- api-key
- cookie:value
- ip
- request-header:value
- tls-fingerprint
- query-string:value
type: string
minItems: 0
type: array
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
nullable: true
type: array
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
type: string
createDate:
description: __Read-only__ The time stamp when you created the rate policy.
example: '2016-07-22T18:57:08.00Z'
format: date-time
readOnly: true
type: string
description:
description: Descriptive text you provide about a policy.
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 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.
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
type: string
name:
description: The name you assign to a rate policy.
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`. Specify `RequestDisabled` to bypass matching on a path.
enum:
- AllRequests
- TopLevel
- Custom
- RequestDisabled
type: string
pathUriPositiveMatch:
description: Whether the condition should trigger on a match (`true`) or a lack of match (`false`).
type: boolean
penaltyBoxDuration:
default: TEN_MINUTES
description: The duration of the penalty box. Either `TEN_MINUTES`, `THIRTY_MINUTES`, `ONE_HOUR`, `FOUR_HOURS`, `SIX_HOURS`, `TWELVE_HOURS`, or `TWENTY_FOUR_HOURS`. Only applicable when the `counterType` is `region_aggregated`.
enum:
- TEN_MINUTES
- THIRTY_MINUTES
- ONE_HOUR
- FOUR_HOURS
- SIX_HOURS
- TWELVE_HOURS
- TWENTY_FOUR_HOURS
type: string
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
type: string
sameActionOnIpv6:
description: Whether to apply the same action to the IPv6 traffic as to the IPv4 traffic.
type: boolean
type:
description: The rate policy type. Either `WAF` for Web Application Firewall, or `BOTMAN` for Bot Manager.
enum:
- WAF
- BOTMAN
type: string
updateDate:
description: __Read-only__ The ISO 8601 timestamp when you last updated the rate policy.
example: '2017-02-22T00:05:41.00Z'
format: date-time
readOnly: true
type: string
useXForwardForHeaders:
description: Whether to check the contents of the `X-Forwarded-For` header in incoming requests.
type: boolean
used:
description: __Read-only__ Whether you're currently using the rate policy.
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
clientIdentifiers:
- 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-22T18:57:08Z'
description: AFW Test Extensions
evaluation:
averageThreshold: 5
burstThreshold: 8
burstW
# --- truncated at 32 KB (250 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/akamai/refs/heads/main/openapi/akamai-shared-resources-rate-policies-api-openapi.yml