The PingOne /environments/{{envID}}/apiServers endpoint provides operations to create, read, update, and delete API servers in PingOne. An API server models a customer’s APIs, which are then protected by the PingOne API access management service.

API server data model {#api-server-data-model}

Property Type? Required? Mutable? Description
authorizationServer Object Required Mutable A container object for properties related to the authorization server that will issue access tokens used to access the APIs.
authorizationServer.resource Relationship Required Mutable The resource defines the characteristics of the OAuth 2.0 access tokens used to get access to the APIs on the API server such as the audience and scopes.
authorizationServer.resource.id UUID Required Mutable A string that specifies the UUID of the custom PingOne resource. This property must identify a PingOne resource with a type property value of CUSTOM.
baseURLs Array Required Mutable An array of string that specifies the possible base URLs that an end-user will use to access the APIs hosted on the customer’s API server. Multiple base URLs may be specified to support cases where the same API may be available from multiple URLs (for example, from a user-friendly domain URL and an internal domain URL). Base URLs must be valid absolute URLs with the https or http scheme. If the path component is non-empty, it must not end in a trailing slash. The path must not contain empty backslash, dot, or double-dot segments. It must not have a query or fragment present, and the host portion of the authority must be a DNS hostname or valid IP (IPv4 or IPv6). The length must be less than or equal to 256 characters.
id UUID Read-only A string that specifies the resource’s unique identifier.
name String Required Mutable A string that specifies the API server resource name. The name value must be unique among all API servers, and it must be a valid resource name.
operations Map Optional Mutable A map from the operation name to the operation object. Each key must be valid ObjectName, and each value must be a valid operation. Each key must be unique within the operations object, which means the operation key is unique within an API server. No duplicate operation values are allowed; operations with the same paths and methods members are not allowed. The operations object is limited to 25 keys (25 individual operations).
operations.key String Optional Mutable A string that specifies the name of the operation.
operations.value Object Optional Mutable An object that specifies attributes of the operation.
operations.value.methods Array Optional Mutable An array that specifies 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.
operations.value.methods.element String Optional Mutable A string that specifies the name of the HTTP method. This value is case-sensitive.
operations.value.paths Array Required Mutable An array that specifies the paths that define the operation. This is a required property when an operations object is specified. 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.
operations.value.paths.element Object Required Mutable An object that defines a pattern that identifies the parent operation.
operations.value.paths.element.pattern String Required Mutable A string that specifies 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 parameter capture. 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 /./.
operations.value.paths.element.type Enum Required Mutable A string that specifies 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 path segment captures.)
operations.value.accessControl Object Optional Mutable An object that specifies the access control configuration for the operation.
operations.value.accessControl.group Object Optional Mutable An object that specifies 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.
operations.value.accessControl.group.groups Array Required Mutable An array that specifies 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 operations.value.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.
operations.value.accessControl.group.groups.element Relationship Required Mutable A Relationship that specifies the ID of the group, wrapped in an object, for future extensibility. This is a required property if operations.value.accessControl.group is set.
operations.value.accessControl.group.groups.element.id UUID Required Mutable A UUID that specifies the group ID. This is a required property if operations.value.accessControl.group is set.

Path parameter pattern syntax

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

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.