PingOne Platform APIs

API Services

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

PingOne enforces a limit of 25 API services per environment.

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 Pagination 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.