PingOne Platform APIs

API Services

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

When you create an API service, PingOne Authorize automatically creates an authorization module associated with that service. The module has its own policy space, which means policies you define within the API service’s module are scoped to that service and evaluated independently. The new module shares the trust framework of the Default module, including attributes, services, processors, and conditions, but maintains a separate space for policies. For more information, refer to Authorization Modules.

PingOne enforces a limit of 25 API services per environment.

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 data model

Property Type Required Mutable Description

accessControl.custom

Object

Optional

Mutable

Defines if the operation will use custom policy rather than the "Group" or "Scope" accessControl requirement.

accessControl.custom.enabled

Boolean

Optional

Mutable

If TRUE, custom policy will be used for the endpoint. Defaults to FALSE.

authorizationServer

Object

Required

Mutable

A container for properties related to the authorization server that will issue access tokens used to access the APIs.

authorizationServer.externalOAuthServer

Object

Optional

Mutable

A container object for fields related to the API service’s external OAuth 2 authorization server. Must not be provided if authorizationServer.type is PINGONE_SSO.

authorizationServer.externalOAuthServer.audience

String

Required

Mutable

The expected audience for incoming access tokens issued by the External OAuth Server. The runtime will reject bearer tokens not issued for this audience by checking for a matching value in the aud claim. The maximum length is 1024.

authorizationServer.externalOAuthServer.id

UUID

Required

Mutable

The ID of the related External OAuth Server.

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 service such as the audience and scopes. Must not be provided if authorizationServer.type is EXTERNAL.

authorizationServer.resource.id

String

Required

Mutable

The UUID of the custom PingOne resource. This property must identify a PingOne resource with a type property value of CUSTOM.

authorizationServer.type

String

Optional

Mutable

The type of authorization server that will issue access tokens. Valid options are PINGONE_SSO or EXTERNAL. Defaults to PINGONE_SSO. Must be the same value as the directory.type. If PINGONE_SSO, the authorizationServer.externalOAuthServer field must not be provided. If EXTERNAL, the authorizationServer.resource field must not be provided.

baseUrls

Array

Required

Mutable

The possible base URLs that an end-user will use to access the APIs hosted on the customer’s API service. 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.

directory

Object

Optional

Mutable

A container object for fields related to the user directory used to issue access tokens for accessing the APIs. If not provided, the directory.type will default to PINGONE_SSO.

directory.type

String

Required

Mutable

The type of directory that will be used to issue access tokens. Valid options are PINGONE_SSO or EXTERNAL. Defaults to PINGONE_SSO. Must be the same value as the authorizationServer.type.

id

String

Optional

Mutable

The resource’s unique identifier.

name

String

Required

Mutable

The API service resource name. The name value must be unique among all API services, and it must be a valid resource name.

policy.id

String

Optional

Read-only

The ID of the root policy.

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 captured with syntax like /{variable}.

  • Nested captures 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.

Limiting and filtering data

You can limit the number of results returned on the Read API Services request with the limit parameter. Refer to Paging and ordering collections for more information about use of the limit parameter, as well as other methods of controlling pagination.

You can filter response data by applying a SCIM filtering expression to the Read API Services request. These SCIM operators can be applied to the following attributes:

  • eq (equals)

    Supported attributes: authorizationServer.externalOAuthServer.id

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 services errors

In addition to the general error codes, API service operations can return the following errors:

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

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<property> <message>] or The request is missing a required value.

When and details

When: A POST /apiServers or PUT /apiServers/{apiServerID} request omits baseUrls, provides an empty array, or provides an array containing a null entry, or omits the authorizationServer.resource.id value required for a PINGONE_SSO authorization server type

Details: must not be null or empty for an omitted or empty baseUrls, or A resource ID must be provided. for an omitted authorizationServer.resource.id, for example Validation Error : [baseUrls must not be null or empty.]

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request. or, for a single-field validator failure, the enumerated template beginning A base URL must 1) be an absolute URL using the 'https' or 'http' scheme

When and details

When: A POST or PUT /apiServers request provides a name that is blank or contains disallowed characters, a baseUrls entry that is not a valid absolute http or https URL with a path that does not end in a slash and has no query, fragment, or empty or dot path segments, an authorizationServer.type of EXTERNAL with a directory type of PINGONE_SSO (or the reverse), an authorizationServer.type of PINGONE_SSO together with authorizationServer.externalOAuthServer, or an authorizationServer.resource.id that does not identify a resource of type CUSTOM

Details: Describes the failing property, such as must not be empty or blank for a blank name, must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for a name with invalid characters, Authorization server type cannot be "PINGONE_SSO" with directory type "EXTERNAL". for a conflicting authorizationServer.type, Authorization server type must not be "PINGONE_SSO" when providing an external OAuth server., or The resource with ID '<resourceId>' is not of type CUSTOM.; for a single-field validator failure, the top-level message is the enumerated base URL template and the detail code is INVALID_VALUE (or UNIQUENESS_VIOLATION for an in-use URL)

400

INVALID_DATA

SIZE_LIMIT_EXCEEDED

Message: The request contains an attribute value that is too large.

When and details

When: A POST or PUT /apiServers request provides more than 10 baseUrls entries or a baseUrls entry longer than 256 characters

Details: No more than 10 base URLs may be specified. for more than 10 entries, or URL length cannot exceed 256 characters. for an over-long entry

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: A resource with the specified name already exists. or, for an in-use baseUrls entry, the enumerated template beginning A base URL must 1) be an absolute URL using the 'https' or 'http' scheme

When and details

When: A POST or PUT /apiServers request specifies a name that already exists in the environment, or a baseUrls entry that is already in use by another API service

Details: The target is name; the message is The name '<apiServerName>' is already in use. For an in-use baseUrls entry, the target is baseUrls[<index>] and the message is The URL '<url>' is already in use by API service '<apiServerName>'.

400

INVALID_DATA

CONSTRAINT_VIOLATION

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

When and details

When: A PUT /apiServers/{apiServerID} request attempts to change the API service deploymentType or type

Details: Deployment type cannot be modified. for a deployment type change attempt or API service type cannot be modified. for an API service type change attempt; the target is deploymentType or type

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A POST or PUT /apiServers request sets authorizationServer.resource.id to a resource already linked to another API service

Details: The target is authorizationServer.resource.id; the message is:

The specified resource is already linked to the API service '<apiServerName>'. A resource can only be linked to one API service.

(or, if more than one existing API service uses the resource, the message is:)

The specified resource is already linked to the following API services: <names>. A resource can only be linked to one API service.

400

REQUEST_FAILED

None

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

When and details

When: A PUT /apiServers/{apiServerID} request modifies an API service while a deployment is in progress

Details: None

400

REQUEST_FAILED

INVALID_PARAMETER

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

When and details

When: A GET /apiServers request provides a negative limit value

Details: The target is limit; the message is Limit parameter value must be a non-negative integer.

400

REQUEST_FAILED

None

Message: Maximum number of API servers have been created in this environment.

When and details

When: A POST /apiServers request would create the environment’s 26th API service

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 does not identify an API service in the environment

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later. for a failed policy tree build on POST, or Failed to build policy tree, try again later on PUT, or Failed to update policy tree, try again later on DELETE.

When and details

When: A custom-policy API service request fails while building the policy tree

Details: None