The external services API provides endpoints to create, read, update, and delete external services resources.

External services data model

Property Description
authSchemes A list of authorization schemes that can be used by a request.
authSchemes.name A string that specifies the name of the authentication scheme. This property is set by the administrator and is unique for each external service. The maximum size is 256 characters. The string can contain unicode letters, combining marks, numeric characters, whitespace, punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$). This is a required property.
authSchemes.type A string that specifies the type of authentication scheme. Options are API_KEY, BEARER, BASIC, and OAUTH_2. This is a required property.
authSchemes.type.{properties} The properties associated with the type of authentication scheme.
  • API_KEY: key (String): required
  • BEARER: token (String): required
  • BASIC:
    • username (String): required
    • password (String): required
  • OAUTH_2:
    • tokenEndpointAuthType (String): Required if type is Oauth. Values can be client_secret_basic or client_secret_post
    • scope (List): optional;
    • tokenEndpoint (String): required
    • clientId (String): required
    • clientSecret (String): required
description A string that specifies the description of the external service. The string can contain unicode letters, combining marks, numeric characters, whitespace, punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
id A string that specifies the resource’s unique identifier.
name A string that specifies the name of the external service. The maximum length for a name is 256 charactersand the name must be unique within the environment. The string can contain unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
requests A list of requests asociated with this external service.
secrets A list of encrypted secret names.
variables A map of variables that can be referenced by requests.

Requests schema data model

Property Description
description A string that specifies the description of the request. The string can contain unicode letters, combining marks, numeric characters, whitespace, punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
displayName A string that specifies the display name of the request. The display name defaults to the method name plus the URL. This value can be edited by the administrator. This property can be used in PingOne interface dropdown menus to select the request. It is comprised of unicode letters, combining marks, numeric characters, whitespace, punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
inputs A list that specifies auto-generated input references in the request configuration.
name A string that specifies the name of the request. A request is executed by its name, which must be unique per external service. Names are comprised of alphanumeric letters, underscore, hyphen, and period (regex: ^[a-zA-Z0-9_. -]+$). Maximum length of 256 characters. This is a required property.
request An object that defines the request properties. This is a required property.
request.authScheme A string that specifies the name of the configured external service auth scheme to use for the request. Options are API_KEY, BEARER, BASIC, and OAUTH_2.
request.method A string that specifies the HTTP method. This is a required property.
request.url A string (in the form of a PEL expression) that specifies the request URL. This is a required property.
request.headers A map of strings that specifies the HTTP request headers to send on invocations of the request. The map of header names to values are a PEL string expression.
request.body An object that specifies the request body type.
request.body.type An enumeration that specifies the request Content-Type. Options are JSON. This is a required property.
request.body.template A string that specifies the request body template, which is a PEL expression of any JSON type. This is a required property.
request.inputSchema A string that specifies the input schema for any inputs that are referenced in any parts of the request. This is a required property if input is configured.
response An object that defines the response properties.
response.output A string (in the form of a PEL expression) that used to generate the response of a request invocation. If this property is not configured, the default value is the following PEL expression: "{\"status\": + response.status, \"headers\": + response.headers, \"body\": + response.body}".
response.outputSchema A string that that specifies the output schema for any output properties that are returned by the request. This is a required property if output is configured.

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.

You need the Environment Admin role to perform operations on external services resources.