Inbound Traffic Policies

The Inbound Traffic Policies service allows you to identify the source of requests to your environment using the service’s verify rules. Then, it allows you to define the structure of the request, including the client IP address and any additional headers. After defining the request structure, access to the environment can be controlled, either through a specified traffic rule or a DaVinci flow that introspects the request’s metadata. Inbound traffic policies are available only through Cloudflare-based Customer Custom Domains (CCDs).

For information about Cloudflare CCDs and migration from legacy CloudFront CCDs, refer to Setting up a custom domain in the PingOne admin documentation.

The /v1/environments/{{envID}}/inboundTrafficPolicies endpoint provides operations to create, read, update, and delete inbound traffic policy confguration resources within a specified environment. To learn more about inbound traffic controls in PingOne, refer to Inbound traffic policies in the PingOne admin documentation.

Inbound traffic policies API limits

PingOne sets the following limits on policies and rules.

Ten (10) inbound traffic policies per environment.
Four (4) VerifyRule objects per inbound traffic policy.
Fifteen (15) HeaderRule objects per per inbound traffic policy.
Sixteen (16) KB limit on the jwks string per verifyRule object.
Five (5) sha256Thumbprints array entries per verifyRule object.
Five (5) sha256Secrets array entries per verifyRule object.
Five (5) cidrRanges array entries per verifyRule.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Inbound traffic policies data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`clientIpRule`	Object	Required	Mutable	An object that defines how the client IP address is set. The client IP address is used for rate limiting and available through DaVinci’s `global.ip` property. Refer to clientIpRule data model for details.
`createdAt`	Date	N/A	Read-only	The time the resource was created.
`enabled`	Boolean	Required	Mutable	Specifies whether the policy is enabled or disabled. A disabled policy is ignored when matching requests. It does not imply that a matching request is blocked.
`environment`	Object	N/A	Read-only	The environment object.
`environment.id`	String	N/A	Read-only	The environment resource’s unique identifier associated with the inbound traffic policy.
`headerRules`	Object[]	Optional	Mutable	An object that defines the custom headers that are available in DaVinci’s `global.currentRequest.connection.headers` property. Refer to headerRules data model for details.
`id`	String	N/A	Read-only	The resource’s unique identifier.
`name`	String	Required	Mutable	The inbound traffic policy’s name, which must be provided and must be unique within an environment.
`priority`	Integer	Required	Mutable	Specifies the order in which the policy is evaluated. A lower priority is evaluated first. Priority values begin at 1. Policies with duplicate priority values are ordered alphabetically by name.
`trafficRule`	Object	Required	Mutable	An object that defines how matching requests are processed. Refer to trafficRule data model for details.
`updatedAt`	Date	N/A	Read-only	The time the resource was last updated.
`verifyRules`	Object[]	Optional	Mutable	An array of zero or more `verifyRule` objects that a request using this policy must match. Each `verifyRule` type appears at most once. A policy with no `verifyRule` entries will match all requests. Refer to Verify rules data model for details.

clientIpRule

Object

Required

Mutable

An object that defines how the client IP address is set. The client IP address is used for rate limiting and available through DaVinci’s global.ip property. Refer to clientIpRule data model for details.

createdAt

Date

N/A

Read-only

The time the resource was created.

enabled

Boolean

Required

Mutable

Specifies whether the policy is enabled or disabled. A disabled policy is ignored when matching requests. It does not imply that a matching request is blocked.

environment

Object

N/A

Read-only

The environment object.

environment.id

String

N/A

Read-only

The environment resource’s unique identifier associated with the inbound traffic policy.

headerRules

Object[]

Optional

Mutable

An object that defines the custom headers that are available in DaVinci’s global.currentRequest.connection.headers property. Refer to headerRules data model for details.

id

String

N/A

Read-only

The resource’s unique identifier.

name

String

Required

Mutable

The inbound traffic policy’s name, which must be provided and must be unique within an environment.

priority

Integer

Required

Mutable

Specifies the order in which the policy is evaluated. A lower priority is evaluated first. Priority values begin at 1. Policies with duplicate priority values are ordered alphabetically by name.

trafficRule

Object

Required

Mutable

An object that defines how matching requests are processed. Refer to trafficRule data model for details.

updatedAt

Date

N/A

Read-only

The time the resource was last updated.

verifyRules

Object[]

Optional

Mutable

An array of zero or more verifyRule objects that a request using this policy must match. Each verifyRule type appears at most once. A policy with no verifyRule entries will match all requests. Refer to Verify rules data model for details.

clientIpRule data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`type`	String	Required	Mutable	Specifies the client IP rule type. Options are `SOCKET` if the IP address is from the connection’s socket, `HEADER` if the IP address is from the header value, and `HEADER_CSV` if the IP address is from an element of a comma-separated header value. For `HEADER` and `HEADER_CSV`, the request must include the header and the indicated value must be an IPv4 or IPv6 address.
`name`	String	Required/Optional	Mutable	The case-insensitive header name. This property is required for `HEADER` and `HEADER_CSV`. For formatting rules, refer to RFC 9110 HTTP Semantics, 5.6.2. Tokens. The maximum name size is 8KB, and the platform disallows name values of: `Authorization`, `Cookie`, `X-Ping-Itp-Jwt`, `X-Ping-Itp-Secret`, `X-Ping-Itp-Id`, and any header beginning with `Cf-`.
`index`	Integer	Required/Optional	Mutable	A 0-based index of comma-separated header value with index starting from the first node in the list. This property is required for `HEADER_CSV`.
`cardinality`	Integer	Required/Optional	Mutable	The expected number of elements in comma-separated header value. This property is required for `HEADER_CSV`.

type

String

Required

Mutable

Specifies the client IP rule type. Options are SOCKET if the IP address is from the connection’s socket, HEADER if the IP address is from the header value, and HEADER_CSV if the IP address is from an element of a comma-separated header value. For HEADER and HEADER_CSV, the request must include the header and the indicated value must be an IPv4 or IPv6 address.

name

String

Required/Optional

Mutable

The case-insensitive header name. This property is required for HEADER and HEADER_CSV. For formatting rules, refer to RFC 9110 HTTP Semantics, 5.6.2. Tokens. The maximum name size is 8KB, and the platform disallows name values of: Authorization, Cookie, X-Ping-Itp-Jwt, X-Ping-Itp-Secret, X-Ping-Itp-Id, and any header beginning with Cf-.

index

Integer

Required/Optional

Mutable

A 0-based index of comma-separated header value with index starting from the first node in the list. This property is required for HEADER_CSV.

cardinality

Integer

Required/Optional

Mutable

The expected number of elements in comma-separated header value. This property is required for HEADER_CSV.

headerRules data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`name`	String	Required	Mutable	The case-insensitive header name. This property is required for `HEADER` and `HEADER_CSV`. For formatting rules, refer to RFC 9110 HTTP Semantics, 5.6.2. Tokens. The maximum name size is 8KB, and the platform disallows header name values of: `Authorization`, `Cookie`, `X-Ping-Itp-Jwt`, `X-Ping-Itp-Secret`, `X-Ping-Itp-Id`, and any header beginning with `Cf-`.
`required`	Boolean	Required	Mutable	Specifies whether the request must include the header (set to `true` if required).

name

String

Required

Mutable

The case-insensitive header name. This property is required for HEADER and HEADER_CSV. For formatting rules, refer to RFC 9110 HTTP Semantics, 5.6.2. Tokens. The maximum name size is 8KB, and the platform disallows header name values of: Authorization, Cookie, X-Ping-Itp-Jwt, X-Ping-Itp-Secret, X-Ping-Itp-Id, and any header beginning with Cf-.

required

Boolean

Required

Mutable

Specifies whether the request must include the header (set to true if required).

trafficRule data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`type`	String	Required	Mutable	Specifies whether matching requests are allowed to proceed. Options are `ALLOW` and `BLOCK`.

type

String

Required

Mutable

Specifies whether matching requests are allowed to proceed. Options are ALLOW and BLOCK.

verifyRule data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`cidrRanges`	String[]	Required/Optional	Mutable	An array that specifies the list of IPv4 and/or IPv6 CIDR subnets for verifying connection IP. This property is required for the `IP_ADDRESS` type.
`jwks`	String	Required/Optional	Mutable	A string in JWK Set format RFC 7517: JSON Web Key (JWK) that specifies the public keys for verifying `X-Ping-Itp-Jwt`. This property is required for the `SIGNATURE` type. The JSON for the JWKS string in the embedded `jwks` property must be formatted as one line with double quotes escaped.
`sha256Thumbprints`	String[]	Required/Optional	Mutable	An array that specifies the list of SHA-256 thumbprints in lowercase hexadecimal for verifying mTLS certificates. This property is required for `MTLS_THUMBPRINT`.
`sha256Secrets`	String[]	Required/Optional	Mutable	An array that specifies the list of SHA-256 secret hashes in lowercase hexadecimal for verifying `X-Ping-Itp-Secret`. The request payload requires these values to be SHA-256 hashed. Each value must be 64 characters in length and be a SHA256 hashed string (`0-9a-f`). This property is required for `SECRET`.
`type`	String	Required	Mutable	Specifies the verify rule type. Options are `SIGNATURE` for signed requests, `MTLS_THUMBPRINT` for mTLS, `SECRET` for shared secret, `IP_ADDRESS` for IP address.

cidrRanges

String[]

Required/Optional

Mutable

An array that specifies the list of IPv4 and/or IPv6 CIDR subnets for verifying connection IP. This property is required for the IP_ADDRESS type.

jwks

String

Required/Optional

Mutable

A string in JWK Set format RFC 7517: JSON Web Key (JWK) that specifies the public keys for verifying X-Ping-Itp-Jwt. This property is required for the SIGNATURE type. The JSON for the JWKS string in the embedded jwks property must be formatted as one line with double quotes escaped.

sha256Thumbprints

String[]

Required/Optional

Mutable

An array that specifies the list of SHA-256 thumbprints in lowercase hexadecimal for verifying mTLS certificates. This property is required for MTLS_THUMBPRINT.

sha256Secrets

String[]

Required/Optional

Mutable

An array that specifies the list of SHA-256 secret hashes in lowercase hexadecimal for verifying X-Ping-Itp-Secret. The request payload requires these values to be SHA-256 hashed. Each value must be 64 characters in length and be a SHA256 hashed string (0-9a-f). This property is required for SECRET.

type

String

Required

Mutable

Specifies the verify rule type. Options are SIGNATURE for signed requests, MTLS_THUMBPRINT for mTLS, SECRET for shared secret, IP_ADDRESS for IP address.

Response codes

Code	Message
200	Successful operation.
201	Successfully created.
204	Successfully removed. No content.
400	The request could not be completed.
401	You do not have access to this resource.
404	The requested resource was not found.

Inbound traffic policy errors

In addition to the general error codes, inbound traffic policy operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`EMPTY_VALUE` or `INVALID_VALUE` or `OUT_OF_RANGE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST /inboundTrafficPolicies` or `PUT /inboundTrafficPolicies/{trafficPolicyID}` request omits a required property (`clientIpRule`, `name`, or `trafficRule`), supplies a `priority` less than 1, exceeds a collection limit (more than 4 `verifyRules`, 15 `headerRules`, 5 `sha256Thumbprints`, 5 `sha256Secrets`, or 5 `cidrRanges` entries), supplies a `jwks` string that is not a well-formed JWK Set or has more than 5 keys, supplies a `sha256Secrets` or `sha256Thumbprints` entry that is not 64-character lowercase hexadecimal, or supplies a `cidrRanges` entry that is not in CIDR notation or is not a valid IPv4 or IPv6 address Details: One detail per failing property, such as `must not be null` for an omitted required property, or `size must be between 1 and 5` for a collection over its limit, for example `Validation Error : [name must not be null]`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT` request supplies a `clientIpRule.name` or `headerRules[].name` that is a reserved header name (`Authorization`, `Cookie`, `X-Ping-Itp-Id`, `X-Ping-Itp-Jwt`, `X-Ping-Itp-Secret`, or `X-Ping-Ingress`), begins with the reserved `cf-` prefix, contains characters outside the RFC 9110 token set, or exceeds 8 KB Details: `'Authorization' is a reserved header name` or `'cf-' is a reserved header prefix` or `must contain only valid HTTP header characters`, for example `Validation Error : [responseHeaders.headers[0] 'Authorization' is a reserved header name]`
400	`INVALID_DATA`	`REQUIRED_VALUE` or `CONSTRAINT_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST` or `PUT` request supplies a rule whose properties do not match its type: a `clientIpRule` of type `SOCKET` with `name`, `index`, or `cardinality` set; a `clientIpRule` of type `HEADER` with `index` or `cardinality` set; a `HEADER` or `HEADER_CSV` client IP rule without a `name`; a `HEADER_CSV` rule without `index` or `cardinality`, or with an `index` greater than or equal to `cardinality`; more than one `verifyRule` of a single type; a `SIGNATURE` rule without `jwks` or `jwksUrl`; an `MTLS_THUMBPRINT` rule without `sha256Thumbprints`; a `SECRET` rule without `sha256Secrets`; an `IP_ADDRESS` rule without `cidrRanges`; a `verifyRule` with properties that do not belong to its type; or duplicate `headerRules` names Details: One detail per violation. Representative messages: `Only SOCKET type rules are allowed if no verify rules are present`, `Client IP Rule of type HEADER or HEADER_CSV must provide a header name`, `Client IP Rule of type HEADER_CSV must provide a cardinality`, `Client IP Rule index cannot be greater than or equal to the cardinality`, `Only one signature verify rule is allowed`, `Signature Rules must provide either jwks or jwksUrl`, `Only jwks or jwksUrl properties can be set for signature rules`, `mTLS Rules must provide sha256Thumbprints to verify mTLS certificates`, `Secret Rules must provide sha256Secrets to verify Connection Secrets`, `IP Address Rules must provide cidrRanges to verify client IP addresses`, `Only one rule allowed for each unique header name`
400	`INVALID_DATA`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /inboundTrafficPolicies` request would exceed 10 inbound traffic policies in the environment Details: `Maximum number of 10 InboundTrafficPolicies reached`
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST` or `PUT` request supplies a `name` that already exists on another inbound traffic policy in the environment Details: `InboundTrafficPolicy with name '<name>' already exists`
400	`INVALID_REQUEST`	`INVALID_VALUE` or None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A path identifier cannot be parsed as a UUID, the request body cannot be deserialized, or a `clientIpRule.type`, `trafficRule.type`, or `verifyRule.type` value is not one of the supported values Details: For a JSON field conversion error (including an unsupported enum value), the target is the field path with message `Invalid value for attribute.`. Otherwise no detail is returned. A path identifier that is not a UUID returns the same body with the message `The request could not be completed. One or more validation errors were in the request.`
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST /inboundTrafficPolicies` request targets an environment with no Cloudflare custom domain with a valid TLS certificate, or a `PUT` request sets `enabled` to `true` for such an environment Details: At least one Cloudflare Custom Domain with a valid TLS certificate must be configured for this environment before creating an inbound traffic policy. or At least one Cloudflare Custom Domain with a valid TLS certificate must be configured for this environment before enabling an inbound traffic policy.
403	`ACCESS_FAILED`	`LICENSE_EXCEEDED`	Message: `The request could not be completed. You do not have access to this resource.` When and details When: The environment’s license does not include the custom-domain capability (all operations) Details: `The request exceeded your license limit.`
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `traffic:create:inboundTrafficPolicy` permission (`POST`), the `traffic:read:inboundTrafficPolicy` permission (`GET` operations), the `traffic:update:inboundTrafficPolicy` permission (`PUT`), or the `traffic:delete:inboundTrafficPolicy` permission (`DELETE`) Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: `GET`, `PUT`, or `DELETE` on `/inboundTrafficPolicies/{trafficPolicyID}` references a policy that does not exist in the environment Details: None.

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE or OUT_OF_RANGE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /inboundTrafficPolicies or PUT /inboundTrafficPolicies/{trafficPolicyID} request omits a required property (clientIpRule, name, or trafficRule), supplies a priority less than 1, exceeds a collection limit (more than 4 verifyRules, 15 headerRules, 5 sha256Thumbprints, 5 sha256Secrets, or 5 cidrRanges entries), supplies a jwks string that is not a well-formed JWK Set or has more than 5 keys, supplies a sha256Secrets or sha256Thumbprints entry that is not 64-character lowercase hexadecimal, or supplies a cidrRanges entry that is not in CIDR notation or is not a valid IPv4 or IPv6 address

Details: One detail per failing property, such as must not be null for an omitted required property, or size must be between 1 and 5 for a collection over its limit, for example Validation Error : [name must not be null]

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT request supplies a clientIpRule.name or headerRules[].name that is a reserved header name (Authorization, Cookie, X-Ping-Itp-Id, X-Ping-Itp-Jwt, X-Ping-Itp-Secret, or X-Ping-Ingress), begins with the reserved cf- prefix, contains characters outside the RFC 9110 token set, or exceeds 8 KB

Details: 'Authorization' is a reserved header name or 'cf-' is a reserved header prefix or must contain only valid HTTP header characters, for example Validation Error : [responseHeaders.headers[0] 'Authorization' is a reserved header name]

400

INVALID_DATA

REQUIRED_VALUE or CONSTRAINT_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request supplies a rule whose properties do not match its type: a clientIpRule of type SOCKET with name, index, or cardinality set; a clientIpRule of type HEADER with index or cardinality set; a HEADER or HEADER_CSV client IP rule without a name; a HEADER_CSV rule without index or cardinality, or with an index greater than or equal to cardinality; more than one verifyRule of a single type; a SIGNATURE rule without jwks or jwksUrl; an MTLS_THUMBPRINT rule without sha256Thumbprints; a SECRET rule without sha256Secrets; an IP_ADDRESS rule without cidrRanges; a verifyRule with properties that do not belong to its type; or duplicate headerRules names

Details: One detail per violation. Representative messages: Only SOCKET type rules are allowed if no verify rules are present, Client IP Rule of type HEADER or HEADER_CSV must provide a header name, Client IP Rule of type HEADER_CSV must provide a cardinality, Client IP Rule index cannot be greater than or equal to the cardinality, Only one signature verify rule is allowed, Signature Rules must provide either jwks or jwksUrl, Only jwks or jwksUrl properties can be set for signature rules, mTLS Rules must provide sha256Thumbprints to verify mTLS certificates, Secret Rules must provide sha256Secrets to verify Connection Secrets, IP Address Rules must provide cidrRanges to verify client IP addresses, Only one rule allowed for each unique header name

400

INVALID_DATA

CONSTRAINT_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /inboundTrafficPolicies request would exceed 10 inbound traffic policies in the environment

Details: Maximum number of 10 InboundTrafficPolicies reached

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request supplies a name that already exists on another inbound traffic policy in the environment

Details: InboundTrafficPolicy with name '<name>' already exists

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A path identifier cannot be parsed as a UUID, the request body cannot be deserialized, or a clientIpRule.type, trafficRule.type, or verifyRule.type value is not one of the supported values

Details: For a JSON field conversion error (including an unsupported enum value), the target is the field path with message Invalid value for attribute.. Otherwise no detail is returned. A path identifier that is not a UUID returns the same body with the message The request could not be completed. One or more validation errors were in the request.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /inboundTrafficPolicies request targets an environment with no Cloudflare custom domain with a valid TLS certificate, or a PUT request sets enabled to true for such an environment

Details:

At least one Cloudflare Custom Domain with a valid TLS certificate must be configured for this environment before creating an inbound traffic policy.

At least one Cloudflare Custom Domain with a valid TLS certificate must be configured for this environment before enabling an inbound traffic policy.

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The environment’s license does not include the custom-domain capability (all operations)

Details: The request exceeded your license limit.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the traffic:create:inboundTrafficPolicy permission (POST), the traffic:read:inboundTrafficPolicy permission (GET operations), the traffic:update:inboundTrafficPolicy permission (PUT), or the traffic:delete:inboundTrafficPolicy permission (DELETE)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: GET, PUT, or DELETE on /inboundTrafficPolicies/{trafficPolicyID} references a policy that does not exist in the environment

Details: None.

PingOne Platform APIs

Inbound Traffic Policies

Inbound traffic policies API limits

Assigning admin roles and permissions to this service

Inbound traffic policies data model

clientIpRule data model

headerRules data model

trafficRule data model

verifyRule data model

Response codes

Inbound traffic policy errors