PingOne Platform APIs

API Operations

The PingOne /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.

API service operations data model

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.

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.