Akamai API Security · Schema
rate-policies
Contains details about rate policies.
API DiscoveryAPI SecurityCloud SecurityPosture ManagementRuntime ProtectionThreat Protection
Properties
| Name | Type | Description |
|---|---|---|
| ratePolicies | array | A list of rate policies in this configuration version. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/akamai-api-security/refs/heads/main/json-schema/api-security-rate-policies-schema.json",
"title": "rate-policies",
"description": "Contains details about rate policies.",
"type": "object",
"properties": {
"ratePolicies": {
"description": "A list of rate policies in this configuration version.",
"items": {
"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` \u2014 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": {
"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"
],
"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\u2019s 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-22 18:57:08.0",
"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 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.",
"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`.",
"enum": [
"AllRequests",
"TopLevel",
"Custom"
],
"type": "string"
},
"pathUriPositiveMatch": {
"description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
"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` \u2014 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-22 00:05:41.0",
"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"
}
},
"type": "array"
}
},
"required": [
"ratePolicies"
],
"additionalProperties": false
}