API Operations

The PingOne /v1/environments/{{envID}}/apiServers/{{apiServerID}}/operations endpoint provides operations to create, read, update, and delete API service operations in PingOne. Each operation is defined by one or more paths, and each path must have a unique pattern.

Path parameter pattern syntax

If a path pattern has a type of PARAMETER, the following syntax rules apply to the parameter expression:

The pattern must start with a slash.
A single * (wildcard) matches any character except a /.
A double ** matches the rest of the path. It cannot be followed by any characters in the pattern.
A path segment can be matched using a named parameter, with syntax like /{variable}.
Nested named parameters are not allowed, meaning {name1{name2}} is an invalid expression.
Partial path segment matches are not allowed, meaning /part1{part2} is an invalid expression.
A literal left curly bracket, right curly bracket, backslash, or wildcard can be matched by preceding the character with a backslash: \{, \{, \\, \*.
The following characters are not allowed in parameter names: '{', '}', '\', '/'.
Parameter names must be unique within an expression, meaning /{name1}/resource/{name1} is an invalid expression.
ASCII control characters are invalid anywhere in the pattern.

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.

API service operations data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`id`	String	N/A	Read-only	The ID of the API service operation. This is randomly generated when the operation is created.
`name`	String	Required	Mutable	The name of the API service operation.
`accessControl`	Object	Optional	Mutable	The access control configuration for the operation.
`accessControl.authentication`	Object	Optional	Mutable	Defines the authentication requirements for this operation. One or both of the `acrs` or `maxAge` fields must be provided.
`accessControl.authentication.acrs`	Array	Optional	Mutable	The `acrs` array is currently limited to a single entry.
`accessControl.authentication.acrs.element`	Object	Required	Mutable	The relationship reference to a PingOne authentication policy.
`accessControl.authentication.acrs.element.id`	String	Required	Mutable	The ID of the authentication policy.
`accessControl.authentication.acrs.element.type`	String	Required	Mutable	Identifies the authentication policy type. Valid values are `PINGONE`, which identifies a sign-on policy, and `DAVINCI`, which identifies a flow policy.
`accessControl.authentication.maxAge`	Number	Optional	Mutable	Specifies the maximum acceptable time in seconds since the user was last authenticated. If provided, the value must be a nonzero positive integer.
`accessControl.group`	Object	Optional	Mutable	The group membership requirements for the operation. The `groups` array must be non-empty when the `group` object is included. The `groups` array must not contain more than 25 elements.
`accessControl.group.groups`	Array	Required	Mutable	The list of groups that define the access requirements for the operation. The end user must be a member of one or more of these groups to gain access to the operation. This is a required property if `accessControl.group` is set. The ID must reference a group that exists at the time the data is persisted. There is no referential integrity between a group and this configuration. If a group is subsequently deleted, the access control configuration will continue to reference that group.
`accessControl.group.groups.element`	Relationship	Required	Mutable	The ID of the group, wrapped in an object, for future extensibility. This is a required property if `operations.value.accessControl.group` is set.
`accessControl.group.groups.element.id`	String	Required	Read-only	A UUID that specifies the group ID. This is a required property if `accessControl.group` is set.
`accessControl.permission`	Object	Optional	Mutable	Defines the application permission requirements for the operation.
`accessControl.permission.id`	string	Required	Mutable	An application permission ID that defines the access requirements for the operation. The end user must be entitled to the specified application permission to gain access to the operation. This is a required property if `accessControl.permission` is set.
`accessControl.scope`	Object	Optional	Mutable	Defines the scope membership requirements for the operation.
`accessControl.scope.matchType`	String	Optional	Mutable	An enumeration defining the match type of the scope rule. `ALL` means the client must be authorized with all scopes configured in the `scopes` array to obtain access. `ANY` means the client must be authorized with one or more of the scopes.
`accessControl.scope.scopes`	Array	Required	Mutable	A list of scopes that define the access requirements for the operation. The client must be authorized with `ANY` or `ALL` of the scopes to be granted access, depending on the `matchType` configuration.
`accessControl.scope.scopes.element`	Object	Required	Mutable	The relationship reference to a PingOne scope.
`accessControl.scope.scopes.element.id`	String	Required	Read-only	The ID of the scope.
`methods`	Array	Optional	Mutable	The methods that define the operation. No duplicates are allowed. Each element must be a valid HTTP token, according to RFC 7230, and cannot exceed 64 characters. An empty array is not valid. To indicate that an operation is defined for every method, the `methods` array should be set to null. The `methods` array is limited to 10 entries.
`methods.element`	String	Optional	Mutable	The name of the HTTP method. This value is case-sensitive.
`paths`	Array	Required	Mutable	The paths that define the operation. The same literal pattern is not allowed within the same operation (the pattern of a `paths` element must be unique as compared to all other patterns in the same `paths` array). However, the same literal pattern is allowed in different operations (for example, OperationA, `/path1`, OperationB, `/path1` is valid). The `paths` array is limited to 10 entries.
`paths.element`	Object	Required	Mutable	The defined pattern that identifies the parent operation.
`paths.element.pattern`	String	Required	Mutable	The pattern used to identify the path or paths for the operation. The semantics of the pattern are determined by the type. For any type, the pattern can contain characters that are otherwise invalid in a URL path. Invalid characters are handled by performing matching against a percent-decoded HTTP request target path. This allows an administrator to configure patterns without worrying about percent encoding special characters. When the `type` is `PARAMETER`, the syntax outlined in the table below is enforced. Additionally, the pattern must contain a wildcard, double wildcard or named parameter. When the `type` is `EXACT`, the pattern can be any byte sequence except for ASCII control characters such as line feeds or carriage returns. The length of the pattern cannot exceed 2048 characters. The path pattern must not contain empty path segments such as `/../`, `//`, and `/./`.
`paths.element.type`	String	Required	Mutable	The type of the pattern. Options are `EXACT` (the verbatim pattern is compared against the path from the request using a case-sensitive comparison) and `PARAMETER` (the pattern is compared against the path from the request using a case-sensitive comparison, using the syntax below to encode wildcards and named parameters).
`policy.id`	String	Optional	Read-only	The ID of the root policy.

id

String

N/A

Read-only

The ID of the API service operation. This is randomly generated when the operation is created.

name

String

Required

Mutable

The name of the API service operation.

accessControl

Object

Optional

Mutable

The access control configuration for the operation.

accessControl.authentication

Object

Optional

Mutable

Defines the authentication requirements for this operation. One or both of the acrs or maxAge fields must be provided.

accessControl.authentication.acrs

Array

Optional

Mutable

The acrs array is currently limited to a single entry.

accessControl.authentication.acrs.element

Object

Required

Mutable

The relationship reference to a PingOne authentication policy.

accessControl.authentication.acrs.element.id

String

Required

Mutable

The ID of the authentication policy.

accessControl.authentication.acrs.element.type

String

Required

Mutable

Identifies the authentication policy type. Valid values are PINGONE, which identifies a sign-on policy, and DAVINCI, which identifies a flow policy.

accessControl.authentication.maxAge

Number

Optional

Mutable

Specifies the maximum acceptable time in seconds since the user was last authenticated. If provided, the value must be a nonzero positive integer.

accessControl.group

Object

Optional

Mutable

The group membership requirements for the operation. The groups array must be non-empty when the group object is included. The groups array must not contain more than 25 elements.

accessControl.group.groups

Array

Required

Mutable

The list of groups that define the access requirements for the operation. The end user must be a member of one or more of these groups to gain access to the operation. This is a required property if accessControl.group is set. The ID must reference a group that exists at the time the data is persisted. There is no referential integrity between a group and this configuration. If a group is subsequently deleted, the access control configuration will continue to reference that group.

accessControl.group.groups.element

Relationship

Required

Mutable

The ID of the group, wrapped in an object, for future extensibility. This is a required property if operations.value.accessControl.group is set.

accessControl.group.groups.element.id

String

Required

Read-only

A UUID that specifies the group ID. This is a required property if accessControl.group is set.

accessControl.permission

Object

Optional

Mutable

Defines the application permission requirements for the operation.

accessControl.permission.id

string

Required

Mutable

An application permission ID that defines the access requirements for the operation. The end user must be entitled to the specified application permission to gain access to the operation. This is a required property if accessControl.permission is set.

accessControl.scope

Object

Optional

Mutable

Defines the scope membership requirements for the operation.

accessControl.scope.matchType

String

Optional

Mutable

An enumeration defining the match type of the scope rule. ALL means the client must be authorized with all scopes configured in the scopes array to obtain access. ANY means the client must be authorized with one or more of the scopes.

accessControl.scope.scopes

Array

Required

Mutable

A list of scopes that define the access requirements for the operation. The client must be authorized with ANY or ALL of the scopes to be granted access, depending on the matchType configuration.

accessControl.scope.scopes.element

Object

Required

Mutable

The relationship reference to a PingOne scope.

accessControl.scope.scopes.element.id

String

Required

Read-only

The ID of the scope.

methods

Array

Optional

Mutable

The methods that define the operation. No duplicates are allowed. Each element must be a valid HTTP token, according to RFC 7230, and cannot exceed 64 characters. An empty array is not valid. To indicate that an operation is defined for every method, the methods array should be set to null. The methods array is limited to 10 entries.

methods.element

String

Optional

Mutable

The name of the HTTP method. This value is case-sensitive.

paths

Array

Required

Mutable

The paths that define the operation. The same literal pattern is not allowed within the same operation (the pattern of a paths element must be unique as compared to all other patterns in the same paths array). However, the same literal pattern is allowed in different operations (for example, OperationA, /path1, OperationB, /path1 is valid). The paths array is limited to 10 entries.

paths.element

Object

Required

Mutable

The defined pattern that identifies the parent operation.

paths.element.pattern

String

Required

Mutable

The pattern used to identify the path or paths for the operation. The semantics of the pattern are determined by the type. For any type, the pattern can contain characters that are otherwise invalid in a URL path. Invalid characters are handled by performing matching against a percent-decoded HTTP request target path. This allows an administrator to configure patterns without worrying about percent encoding special characters.
When the type is PARAMETER, the syntax outlined in the table below is enforced. Additionally, the pattern must contain a wildcard, double wildcard or named parameter. When the type is EXACT, the pattern can be any byte sequence except for ASCII control characters such as line feeds or carriage returns. The length of the pattern cannot exceed 2048 characters. The path pattern must not contain empty path segments such as /../, //, and /./.

paths.element.type

String

Required

Mutable

The type of the pattern. Options are EXACT (the verbatim pattern is compared against the path from the request using a case-sensitive comparison) and PARAMETER (the pattern is compared against the path from the request using a case-sensitive comparison, using the syntax below to encode wildcards and named parameters).

policy.id

String

Optional

Read-only

The ID of the root policy.

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.
403	You do not have permissions or are not licensed to make this request.
404	The requested resource was not found.

API service operations errors

In addition to the general error codes, API service operation 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 `REQUIRED_VALUE`	Message: `Validation Error : [<property> <message>]` or `One or more issues were found in the request data.` When and details When: A `POST` or `PUT /apiServers/{apiServerID}/operations` request omits `name` or `paths`, provides an empty `paths` array, or omits an element ID required by a configured access control rule Details: `must not be null or empty` for an omitted or blank `name`, `must not be null or empty` for an omitted or empty `paths` array, `The scope ID value is required.` for a scope rule element without an `id`, `The authentication policy ID value is required.` and `The authentication policy type is required.` for an `accessControl.authentication.acrs` element missing those values, or `An application permission ID value is required.` for an `accessControl.permission.id` that is omitted, for example `Validation Error : [name must not be null or empty]`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` or `One or more issues were found in the request data.` When and details When: A `POST` or `PUT /apiServers/{apiServerID}/operations` request provides a `name` that is blank or exceeds the maximum length, `methods` entries that are not valid unique HTTP methods or exceed 64 characters, a `paths` pattern that is invalid for its type (missing a leading slash, containing a query parameter, fragment, empty or dot path segment, or ASCII control characters, exceeding 2048 characters, or being a duplicate within the operation), an invalid `PARAMETER` pattern expression, a `paths` array longer than 10 entries, a `methods` array longer than 10 entries, or access control references that do not exist or are not related to the API service’s resource Details: `Operation name must not be empty or blank.` for a blank `name`, `Operation name must be between 1 and 256 characters.` for an over-long `name`, `must include only unique HTTP methods` for duplicate `methods` entries, `must be 64 characters or fewer` for an over-long method, `must not include duplicate paths` for a duplicate pattern, `Pattern "<pattern>" must start with "/"` for a pattern without a leading slash, `The path pattern "<pattern>" must not contain query parameters` or `must not contain a fragment`, `The path pattern "<pattern>" must not be longer than 2048`, `The path pattern "<pattern>" must not contain an empty or dot path segment`, `Path expression must start with a '/'` and `Parameter with name '<name>' already exists` for invalid `PARAMETER` expressions, or `The group with ID '<groupID>' does not exist.` and `The authentication policy with ID '<policyID>' and type '<type>' does not exist.` for references that do not resolve
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `A resource with the specified name already exists.` When and details When: A `POST` or `PUT /apiServers/{apiServerID}/operations` request specifies a `name` that already exists within the same API service Details: The target is `name`; the message is `the Operation name "<operationName>" cannot be used twice within the API Service`.
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Invalid value for attribute.` When and details When: A `POST` or `PUT /apiServers/{apiServerID}/operations` request configures a `scopes` or `permission` rule on an API service whose authorization server type is `EXTERNAL`, or a `groups` or `permission` rule on an API service whose directory type is `EXTERNAL` Details: `Cannot configure a scopes rule for an API Service with authorization server type EXTERNAL` with target `accessControl.scope`, `Cannot configure a permission rule for an API Service with authorization server type EXTERNAL` with target `accessControl.permission`, `Cannot configure a groups rule for an API Service with directory type EXTERNAL` with target `accessControl.group`, or `Cannot configure a permission rule for an API Service with directory type EXTERNAL` with target `accessControl.permission`.
400	`INVALID_DATA`	None	Message: `Maximum number of operations have been created for this API service.` When and details When: A `POST /apiServers/{apiServerID}/operations` request would exceed the maximum number of operations for the API service (25, or 100 when the modules feature is enabled) Details: None
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request violates a constraint imposed by the service.` When and details When: A `POST` or `PUT /apiServers/{apiServerID}/operations` request configures a `scopes` or application `permission` rule when the API service has no PingOne SSO resource, configures an authentication requirements rule when the API service’s authorization server type is not `PINGONE_SSO`, or creates an operation on an MCP API service Details: `The scopes access control rule cannot be configured because the API service’s PingOne SSO resource is undefined` with target `accessControl.scope`: The application permission access control rule cannot be configured because the API service's PingOne SSO resource is undefined with target `accessControl.permission`: The authentication requirements rule cannot be configured because the API service does not use an authorizationServer type of PINGONE_SSO. with target `accessControl.authentication`, or `An operation cannot be created when the API Service type is MCP.` with no target.
400	`REQUEST_FAILED`	`INVALID_PARAMETER`	Message: `The request could not be completed. There was an issue processing the request.` for a negative `limit`, or `The request could not be completed. The request was malformed or invalid.` for an invalid `expand` value When and details When: A `GET /apiServers/{apiServerID}/operations` request provides a negative `limit` value, or a `GET /apiServers/{apiServerID}/operations/{apiServerOperationID}` request provides an `expand` value that is not a comma-separated list of `authenticationPolicies`, `groups`, and/or `scopes` Details: The target is `limit`; the message is `Limit parameter value must be a non-negative integer.` For an invalid `expand` value, the target is `expand` and the message is: The 'expand' parameter value must be a comma-separated list consisting only of the values 'authenticationPolicies', 'groups', and/or 'scopes'
400	`REQUEST_FAILED`	None	Message: `API service and operations cannot be modified while a deployment is in progress.` When and details When: A `POST`, `PUT`, or `DELETE /apiServers/{apiServerID}/operations` request modifies an API service whose deployment is in progress Details: None
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `authz:read:apiServer` permission (`GET` operations), the `authz:create:apiServer` permission (`POST`), the `authz:update:apiServer` permission (`PUT`), or the `authz:delete:apiServer` 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: The `apiServerID` or `apiServerOperationID` does not identify a resource in the environment, or a `GET` operation targets an MCP API service, which does not support operations Details: None
500	`UNEXPECTED_ERROR`	None	Message: `Failed to build policy tree, try again later` When and details When: The operation fails unexpectedly while building the policy tree for a custom-policy API service Details: None

400

INVALID_DATA

EMPTY_VALUE or REQUIRED_VALUE

Message: Validation Error : [<property> <message>] or One or more issues were found in the request data.

When and details

When: A POST or PUT /apiServers/{apiServerID}/operations request omits name or paths, provides an empty paths array, or omits an element ID required by a configured access control rule

Details: must not be null or empty for an omitted or blank name, must not be null or empty for an omitted or empty paths array, The scope ID value is required. for a scope rule element without an id, The authentication policy ID value is required. and The authentication policy type is required. for an accessControl.authentication.acrs element missing those values, or An application permission ID value is required. for an accessControl.permission.id that is omitted, for example Validation Error : [name must not be null or empty]

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>] or One or more issues were found in the request data.

When and details

When: A POST or PUT /apiServers/{apiServerID}/operations request provides a name that is blank or exceeds the maximum length, methods entries that are not valid unique HTTP methods or exceed 64 characters, a paths pattern that is invalid for its type (missing a leading slash, containing a query parameter, fragment, empty or dot path segment, or ASCII control characters, exceeding 2048 characters, or being a duplicate within the operation), an invalid PARAMETER pattern expression, a paths array longer than 10 entries, a methods array longer than 10 entries, or access control references that do not exist or are not related to the API service’s resource

Details: Operation name must not be empty or blank. for a blank name, Operation name must be between 1 and 256 characters. for an over-long name, must include only unique HTTP methods for duplicate methods entries, must be 64 characters or fewer for an over-long method, must not include duplicate paths for a duplicate pattern, Pattern "<pattern>" must start with "/" for a pattern without a leading slash, The path pattern "<pattern>" must not contain query parameters or must not contain a fragment, The path pattern "<pattern>" must not be longer than 2048, The path pattern "<pattern>" must not contain an empty or dot path segment, Path expression must start with a '/' and Parameter with name '<name>' already exists for invalid PARAMETER expressions, or The group with ID '<groupID>' does not exist. and The authentication policy with ID '<policyID>' and type '<type>' does not exist. for references that do not resolve

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: A resource with the specified name already exists.

When and details

When: A POST or PUT /apiServers/{apiServerID}/operations request specifies a name that already exists within the same API service

Details: The target is name; the message is the Operation name "<operationName>" cannot be used twice within the API Service.

400

INVALID_DATA

INVALID_VALUE

Message: Invalid value for attribute.

When and details

When: A POST or PUT /apiServers/{apiServerID}/operations request configures a scopes or permission rule on an API service whose authorization server type is EXTERNAL, or a groups or permission rule on an API service whose directory type is EXTERNAL

Details: Cannot configure a scopes rule for an API Service with authorization server type EXTERNAL with target accessControl.scope, Cannot configure a permission rule for an API Service with authorization server type EXTERNAL with target accessControl.permission, Cannot configure a groups rule for an API Service with directory type EXTERNAL with target accessControl.group, or Cannot configure a permission rule for an API Service with directory type EXTERNAL with target accessControl.permission.

400

INVALID_DATA

None

Message: Maximum number of operations have been created for this API service.

When and details

When: A POST /apiServers/{apiServerID}/operations request would exceed the maximum number of operations for the API service (25, or 100 when the modules feature is enabled)

Details: None

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A POST or PUT /apiServers/{apiServerID}/operations request configures a scopes or application permission rule when the API service has no PingOne SSO resource, configures an authentication requirements rule when the API service’s authorization server type is not PINGONE_SSO, or creates an operation on an MCP API service

Details: The scopes access control rule cannot be configured because the API service’s PingOne SSO resource is undefined with target accessControl.scope:

The application permission access control rule cannot be configured because the API service's PingOne SSO resource is undefined

with target accessControl.permission:

The authentication requirements rule cannot be configured because the API service does not use an authorizationServer type of PINGONE_SSO.

with target accessControl.authentication, or An operation cannot be created when the API Service type is MCP. with no target.

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request. for a negative limit, or The request could not be completed. The request was malformed or invalid. for an invalid expand value

When and details

When: A GET /apiServers/{apiServerID}/operations request provides a negative limit value, or a GET /apiServers/{apiServerID}/operations/{apiServerOperationID} request provides an expand value that is not a comma-separated list of authenticationPolicies, groups, and/or scopes

Details: The target is limit; the message is Limit parameter value must be a non-negative integer. For an invalid expand value, the target is expand and the message is:

The 'expand' parameter value must be a comma-separated list consisting only of the values 'authenticationPolicies', 'groups', and/or 'scopes'

400

REQUEST_FAILED

None

Message: API service and operations cannot be modified while a deployment is in progress.

When and details

When: A POST, PUT, or DELETE /apiServers/{apiServerID}/operations request modifies an API service whose deployment is in progress

Details: None

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the authz:read:apiServer permission (GET operations), the authz:create:apiServer permission (POST), the authz:update:apiServer permission (PUT), or the authz:delete:apiServer 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: The apiServerID or apiServerOperationID does not identify a resource in the environment, or a GET operation targets an MCP API service, which does not support operations

Details: None

500

UNEXPECTED_ERROR

None

Message: Failed to build policy tree, try again later

When and details

When: The operation fails unexpectedly while building the policy tree for a custom-policy API service

Details: None

PingOne Platform APIs

API Operations

Path parameter pattern syntax

Assigning admin roles and permissions to this service

API service operations data model

Response codes

API service operations errors