PingOne Platform API Reference - Early Access

PingOne is a cloud-based framework for secure identity access management. The PingOne API gives developers the tools to integrate enterprise and third-party applications with the PingOne platform.

This document describes a number of PingOne services, including the Management API services, the Authentication API services, and the Multi-factor Authentication services. There is also material in this document that refers to the integrations between the PingOne platform and other Ping products that facilitate extended functionality beyond PingOne.

For architectural and background information, see PingOne for Developers Foundations. For a guided walkthrough using the PingOne APIs, see PingOne for Developers Getting Started.

New to PingOne?

If you're new to PingOne, the following topic links will help you learn more and start working with the PingOne API.

Beta Topics

Flows and Forms

The beta topics in Flows and Forms document the deprecated Flow Definitions service in PingOne. The Flow Definitions service was replaced by PingOne DaVinci.

External Services Management

The external services API allows you to make outbound HTTP requests from PingOne to an external resource server. It functions like a PingOne HTTP client. By configuring an external service resource in PingOne, you configure how to send an HTTP request at invocation time.

PingOne external services configurations integrate with PingOne flows, which allows for outbound HTTP requests in the context of a flow.

Terminology

  • External Service

    External services are a group of requests and additional configuration information to support the requests. Some configuration properties, such as variables and secrets, can be referenced by any of the external service’s requests.

  • Request

    The HTTP request configuration includes properties such as a URL, headers, and body to define the request to the external resource server. When an external service request is invoked, PingOne uses the defined configuration to create and send an HTTP request.

  • PingOne's expression language

    External service requests use PingOne's expression language, which is based on SPEL, to give you flexibility to define complex configuration attributes. For more information, see PingOne's expression language.

Frequently asked questions

How do I resolve an expression error?

When you invoke an external service request you may get an expression error. The error should provide clues on what went wrong. For more information about PingOne's expression language, see PingOne's expression language. It is also important to remember that all inputs must be strings.

How do I change the request configuration at invocation time?

If you need to have the URL, a header, or body parameter be dynamic per request, then you must use inputs. You can reference an input in the request configuration (inputs.myInputName) and then at invocation time send the input in. For examples of this action, see the “Getting Started” topic.

What happens when I invoke an external service request?

PingOne finds your configuration by environment ID, external service ID, and request name. The configuration is then used to generate and send an HTTP request. As a part of generating an HTTP request, the configuration is scanned for variables, secrets, and input references, and these rferences are resolved to concrete values. The HTTP request is sent and the response is by default mapped to { status: <status>, headers: <responseHeaders>, body: <responseBody> }.

How do I avoid duplicating configuration across multiple external service requests?

If you have requests that need the same information (like a URL or header value) you can use variables or secrets (or both). The difference between the two is that secrets are encrypted and managed through a separate endpoint for stricter administrative control.

How do I protect a sensitive value like an API key or secret?

Configure a secret for the external service and then reference it in your request configuration.

How do I configure authentication on an external service request?

If it is a header-based authentication, you can set a header on the request and use a secret for the value.

How do I fix an error that I’m getting when trying to invoke an external service request?

You may be encountering one of the following error reasons:

  • SSL_HANDSHAKE_FAILED

    When sending the outbound HTTP request the SSL handshake failed. Please check your configuration.

  • NO_HTTP_RESPONSE

    We sent the outbound HTTP request but did not get an HTTP response from the server.

  • TIMEOUT

    We sent the outbound HTTP request but did not get an HTTP response in the time allowed. The timeout is 8 seconds.

  • TOO_MANY_INVOCATIONS

    We did not send the outbound HTTP request because a limit was reached. You are allowed 45 concurrent outbound HTTP requests per environment.

  • MALICIOUS_URL

    The URL targeted a host that we determine to be malicious.

  • INVOCATION_FAILED

    There was an error likely unrelated to your configuration or targeted service. If this error persists please contact support.

  • INVOCATION_ERROR

    We did not send the outbound HTTP request and it is likely because of a reason with your configuration. There may be details on the error giving more details.

Data models

See the following topics for data model property definitions:

Getting Started with External Services

The Getting Started topics show you how to create an external service with four requests:

  • one request that uses static values
  • one request that uses a variable
  • one request that uses a secret
  • one request that uses an input

After creating the external service configuration with these four requests successfully, additional topics show you how to invoke all four external service requests.

Click the Run in Postman button below to download a Postman collection that includes the requests described in this section.

Run in Postman

Create your first external service

Add your first request to the external service

Invoke your first request

Add a variable and use it in a request

Invoke your request that uses a variable

Add a secret and use it in a request

Add requests that use a variable and a secret

Invoke your request that uses a secret

Add invocation inputs in a request

Invoke your request that uses an input

External Services

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 PingOne's expression language) 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 (in PingOne's expression language).
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 (in PingOne's expression language) that specifies the request body template, which is 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 PingOne's expression language) that used to generate the response of a request invocation. If this property is not configured, the default value is the following expression (in PingOne's expression language): "{\"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.

CREATE External Service

READ External Services

READ One External Service

UPDATE External Service

DELETE External Service

External Services Secrets

The external services secrets endpoint provides operations to read and update the external service secret. The name property of the external service secret must be unique within the environment. A secret resource is a name-value pair configured by the administrator and applicable to the entire external service. Secret values are encrypted and can be referenced in the external service configuration.

External services secrets data model
Property Description
name A string that specifies the name of the external service secret. This property is set by the administrator and is unique for each external service. This is a required property.
value A string that specifies the value of the external service secret. This is a required property.
Response codes
Code Message
200 Successful operation.
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.

READ External Service Secrets

UPDATE External Service Secrets

External Services Requests

The external services requests endpoint provides operations to invoke the external service request. The inputs property specifies the inputs required by the request. The request can have several inputs, specified in the following format in the request body:

{
    "inputs": {
        "input1": "input1Value",
        "input2": {
            "aProperty": "aValue"
        },
        "input3": [ { "aProperty": "aValue" } ]
    }
}
External services invocation request data model
Property Description
inputs A JSON map that specifies the input properties required by the request. All input properties needed by the request must be defined in the input JSON. Otherwise, the request will fail. This is a required property if the request requires input properties. If the request does not require any input, this property can be omitted.
External services invocation response data model
Property Description
outputs A JSON map that specifies the response dictated by the external service's response mapped by request's response output configuration. The value could be any JSON type, based on the request's response output configuration. This is a required property.
Response codes
Code Message
200 Successful operation.
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.

Invoke External Service Request

Flow Definitions

Flow definitions define a series of steps that designate the actions of a workflow. The flow execution endpoint references a flow definition resource that specifies an initial step and all additional steps required to complete the flow execution. For more information about flow executions, see Flow Executions.

Flow definitions include step definitions that define an operational step to perform a specific work action, which generates output that is processed by the flow. A flow step can also designate flow-control actions that branch or end the flow. For more information, see Flow Definition Steps.

The flow definitions API provides operations to create, read, update, and delete flow definitions. It also provides endpoints to get and enhance flow definition step schema metadata. For information about flow definition step schema metadata, see Flow Definition Steps.

Flow definitions data model
Property Description
description A string that specifies the description of the flow definition.
enabled A boolean that specifies whether the flow is enabled. Disabled flows cannot be executed. This is a required property.
environment.id A string that specifies the environment ID associated with this flow definition resource.
id A string that specifies the resource’s unique identifier.
name A string that specifies the flow definition name, which must be provided and must be unique within an environment.
trigger A predefined trigger that can initiate the flow definition execution. The trigger marks the step definition from which the flow starts.
trigger.configuration An object that specifies the trigger configuration data.
trigger.inputs An object that specifies the trigger-specific inputs.
trigger.next A string that specifies the first step definition to execute.
trigger.type A string that specifies the type of trigger. Options are EXPERIENCE and SIGN_ON_POLICY. For more information about trigger types, see READ Trigger Type Metadata.
stepDefinitions A map that specifies the step definitions available in the flow definition, differentiated by a human-readable identifier as the key. The key must be a string with unicode letters, numeric characters, underscore, and dash: ^[\p{L}\p{N}_-]+$. This key is used in variable paths to reference outputs from the step at runtime (for example, ${steps.login.outputs.something}).
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.

CREATE Flow Definition Basic (EXPERIENCE trigger)

CREATE Flow Definition Basic (SIGN_ON_POLICY trigger)

CREATE Agreement Consent Flow Definition (EXPERIENCE trigger)

CREATE Agreement Consent Flow Definition (SIGN_ON_POLICY trigger)

CREATE Agreement Consent Flow Definition (SIGN_ON_POLICY trigger) Copy

CREATE Agreement Reconsent Flow Definition (EXPERIENCE trigger)

CREATE Agreement Reconsent Flow Definition (EXPERIENCE trigger) Copy

CREATE Agreement Reconsent Flow Definition (SIGN_ON_POLICY trigger)

CREATE Agreement Reconsent Flow Definition (SIGN_ON_POLICY trigger) Copy

CREATE Registration Flow Definition (Experience)

CREATE Registration Flow Definition (Sign-on Policy)

CREATE Registration with Consent Flow Definition (Sign-on Policy)

CREATE MFA Enrollment (EXPERIENCE trigger)

CREATE MFA Enrollment (SIGN_ON_POLICY trigger)

CREATE MFA Challenge (EXPERIENCE trigger)

CREATE MFA Challenge (SIGN_ON_POLICY trigger)

CREATE Sign On (EXPERIENCE trigger)

CREATE Sign On (SIGN_ON_POLICY trigger)

CREATE Identity Provider Sign On (SIGN_ON_POLICY trigger)

CREATE Password Recovery (EXPERIENCE trigger)

CREATE Password Recovery (SIGN_ON_POLICY trigger)

READ Flow Definitions

READ One Flow Definition

UPDATE Flow Definition

DELETE Flow Definition

READ Step Type Metadata

READ Trigger Type Metadata

Enrich Step Type Metadata

Flow Definition Steps

Flow definition steps specify the actions of a workflow. The step definition performs a specific operation, which generates output that is processed by the flow. A flow step can also designate flow-control actions that branch or end the flow.

Step definitions data model
Property Description
configuration An object that specifies the step type specific configuration properties as described and validated by the step type metadata.
description A string that specifies the description of the description for this step type as defined by the administrator.
displayName A string that specifies the display name for this step.
iconURL A string that specifies the icon for this step type as defined in the step type metadata.
input An object that specifies the step type specific input properties as described by the step type metadata. Any use of placeholders are resolved at execution time.
outlets An object that specifies the set of results a step definition can produce.
outlets.result An object that specifies the result to handle. Valid results for the specified step type are defined in the step type metadata. An outlet for the ERROR result may be used with any step definition to handle errors from the step. If an outlet for the ERROR result is not defined, errors from the step result in a failed flow.
outlets.result.displayName A string that specifies the display name for this result as defined in the step type metadata.
outlets.result.description A string that specifies the description for this result as defined in the step type metadata.
outlets.result.next A string that specifies the next step definition key in the sequence. This value must point to an existing step definition instance.
type A string that specifies the step definition type. There are several step definition type options. The supported step definition types are best viewed by running the /flowMetadata/stepTypes endpoint. For more information, see READ Step Type Metadata.
Step type metadata data model
Property Description
configurationSchema A JSON schema object that defines a structure of step definition configuration properties that are expected for a specific type. Step definitions are validated against a submitted step definition. For more information about the JSON Schema specification, see JSON Schema.
configurationUiSchema A JSON schema object that defines the user interface representation of the step configuration.
description A string that specifies the description of the step type.
displayName A string that specifies the display name for this step.
iconUrl A string that specifies the URL for the step icon in the user interface.
inputSchema A JSON schema object that defines the input structure of step definition configuration properties that are expected for a specific type. For more information about the JSON Schema specification, see JSON Schema.
configurationUiSchema A JSON schema object that defines the user interface representation of the step configuration. For more information about the JSON Schema specification, see JSON Schema.
configurationUiSchema A JSON schema object that defines the user interface representation of the step configuration.
resultMetadata An object that lists all the expected results of a step.
resultMetadata.description A string that specifies the description represented in the user interface.
resultMetadata.displayName A string that specifies the display name represented in the user interface.
resultMetadata.outputSchema A JSON schema object that specifies the expected structure of the response that the result can provide.
resultMetadata.typeName A string that specifies the step definition type name. The name cannot be ERROR because this is a reserved type name. For more information about step definition type options, see READ Step Type Metadata.
version A string that specifies the step type version.
Step type metadata enrichment data model
Property Description
configuration An object that specifies a step definition configuration that can be used as part of the enrichment process. This value should match the configurationSchema of the stepType for which the request is submitted.
trigger An object that specifies a source trigger under which the steps should be enriched. This is a required property.
trigger.configuration An object that specifies optional trigger specific properties.
trigger.type A string that specifies a unique trigger type. This is a required property.
Flow and step definition context placeholders
Parameter Description
${flow.*} The current flow execution state. For example, ${flow.inputs.parameters.applicationId}.
${steps.stepName.outputs.*} The current step execution state, where stepName designates the name of the step. For example, ${steps.registrationForm.outputs.formData.user}.

Flow definition step types

The following section documents the supported flow definition step types and the request schema, response schema, the supported results, and the custom content type (if applicable) associated with any step type actions.

For more information about flow definitions and step types, see Flow Definitions.

This step type specifies a user's consent to an agreement. The result reflects the user's decision to consent to an agreement and saves the user's consent.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the AGREEMENT_CONSENT_ACCEPT step type.
Input property Description
user.id A string that specifies the user ID associated with the saved consent.
agreementConsent.agreement.id A string that specifies the agreement ID associated with the saved consent. This resource provides details containing user information and the agreement information to which the user has provided consent.
agreementConsent.consentedAt The date and time when the consent decision was made.
agreementConsent.language.id A string that specifies the language ID associated with the agreement to which the user has given consent.
agreementConsent.revision.id A string that specifies the revision ID associated with the agreement to which the user has given consent.

The following properties are returned for the SAVED result.

Output property Description
agreementConsent.status A string that specifies the current status of user's consent in relation to this agreement.
agreementConsent.id A string that specifies the agreement consent ID associated with this agreement.
agreementConsent.agreement.id A string that specifies the agreement ID associated with this agreement consent.
agreementConsent.language.id A string that specifies the language ID associated with the agreement to which the user has given consent.
agreementConsent.revision.id A string that specifies the revision ID associated with the agreement to which the user has given consent.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the AGREEMENT_CONSENT_ACCEPT step type.
Parameters Description
There are no flow action parameters associated with the AGREEMENT_CONSENT_ACCEPT step type.

This step type specifies a request for consent from the user. Submitting the form initiates a user.consent action to accept or deny consent to the agreement. The following step type definition properties are used with flow definition and flow execution resources.

Step properties used with flow definitions
Configuration schema property Description
agreement.id A string that specifies the agreement ID for the agreement that requires user consent.
Input property Description
There are no input properties for the AGREEMENT_CONSENT_FORM step type.

The following properties are returned for the ACCEPTED result.

Output property Description
agreementConsent.status A string that specifies the current status of user's consent in relation to this agreement.
agreementConsent.agreement.id A string that specifies the agreement ID associated with this agreement consent.
agreementConsent.consentedAt The date and time when the consent decision was made.
agreementConsent.language.id A string that specifies the language ID associated with the agreement to which the user has given consent.
agreementConsent.revision.id A string that specifies the revision ID associated with the agreement to which the user has given consent.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
user.consent The link to initiate the consent action. The action must provide a value for the accept property and specify application/vnd.pingidentity.user.consent+json as the custom content type in the request.
Parameters Description
accept A boolean that specifies whether the user accepts the agreement.

Agreement Reconsent Form

This step type specifies a request for consent from the user to update the user's consent to an agreement. This step presents a form to the end user to prompt for renewed consent to an agreement. Submitting the form initiates a user.consent action to accept or deny consent to the agreement.

Step properties used with flow definitions
Configuration schema property Description
agreement.id A string that specifies the agreement ID for the agreement that requires user consent.
Input property Description
user.id A string that specifies the user ID associated with the saved consent.
user.preferredLanguage A string that specifies the user's perferred language.

The following properties are returned for the SAVED result.

Output property Description
agreementConsent.status A string that specifies the current status of user's consent in relation to this agreement.
agreementConsent.id A string that specifies the agreement consent ID associated with this agreement.
agreementConsent.agreement.id A string that specifies the agreement ID associated with this agreement consent.
agreementConsent.language.id A string that specifies the language ID associated with the agreement to which the user has given consent.
agreementConsent.revision.id A string that specifies the revision ID associated with the agreement to which the user has given consent.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
user.consent The link to initiate the consent action. The action must provide a value for the accept property and specify application/vnd.pingidentity.user.consent+json as the custom content type in the request.
Parameters Description
accept A boolean that specifies whether the user accepts the agreement.

API Request

This step type makes an API request to a third-party service.

Step properties used with flow definitions
Configuration schema property Description
method A string that specifies the request method type. Options are GET, POST, PUT, PATCH, and DELETE.
Input property Description
url A string that specifies the request URL.
query An object that specifies the query parameters to include on the request.
headers An object that specifies the HTTP headers to include on the request.
body A string that specifies the body of the request.

The following properties are returned for the SUCCEEDED result.

Output property Description
agreementConsent.status A string that specifies the current status of user's consent in relation to this agreement.
agreementConsent.id A string that specifies the agreement consent ID associated with this agreement.
agreementConsent.agreement.id A string that specifies the agreement ID associated with this agreement consent.
agreementConsent.language.id A string that specifies the language ID associated with the agreement to which the user has given consent.
agreementConsent.revision.id A string that specifies the revision ID associated with the agreement to which the user has given consent.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the API_REQUEST step type.
Parameters Description
There are no flow action parameters associated with the API_REQUEST step type.

Branch

This step type branches the flow based on one or more conditions. The step returns a NO_MATCH result if no condition is met. For information about the common policy language used to specify conditions, see Sign-On Policy Actions.

Step properties used with flow definitions
Configuration schema property Description
conditions An array of conditions to be evaluated.
conditions.condition An object that is defined using the common policy language to define a flow condition to match.
conditions.result A string that specifies the result when this specific flow condition is matched.
conditions.displayName A string that specifies the display name for the result.
Input property Description
There are no configuration schema properties for the BRANCH step type.

The following properties are returned for the NO_MATCH result.

Output property Description
There are no output properties for the BRANCH step type.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the BRANCH step type.
Parameters Description
There are no flow action parameters associated with the BRANCH step type.

Complete Flow

This step type completes the flow and returns a result.

Step properties used with flow definitions
Configuration schema property Description
result An object that specifies the result needed to complete the flow. Results are defined by the trigger type used by this flow. Enumerations are dynamically generated at configuration time of conditions to be evaluated.
Input property Description
{{someProperty}} An object that specifies the flow output. Properties are derived dynamically based on the configured result.
Output property Description
There are no output properties for the COMPLETE_FLOW step type.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the COMPLETE_FLOW step type.
Parameters Description
There are no flow action parameters associated with the COMPLETE_FLOW step type.

Create Risk Evaluation

This step type creates a risk evaluation in PingOne.

Step properties used with flow definitions
Configuration schema property Description
riskPolicySet.id A string that specifies the risk policy set to use for risk evaluation.
useDefaultPolicy A boolean that specifies whether to use the environment's default policy set for the risk evaluation. If this property is set to false, a risk policy set ID must be specified in the riskPolicySet.id property.
profileDevice A boolean that specifies whether the device will be profiled during the step execution. If the value of this property is set to true, the step prompts for a device profile action.
Input property Description
riskEvaluation.event.targetResource.id A string that specifies the ID of the target application, which is the application the user attempts to access.
riskEvaluation.event.targetResource.name A string that specifies the name of the target application, which is the application the user attempts to access. The riskEvaluation.event.targetResource is an optional property, but if the riskEvaluation.event.targetResource.name property is specified, then the riskEvaluation.event.targetResource.id property must also be specified.
riskEvaluation.event.ip A string that specifies the origin IP address. This is a required property.
riskEvaluation.event.flow.type A string that specifies the flow type. The default value is AUTHENTICATION.
riskEvaluation.event.user.name A string that specifies the name of the user associated with the risk evaluation.
riskEvaluation.event.user.type A string that specifies the type of user associated with the risk evaluation. Options are EXTERNAL and PING_ONE. This is a required property.
riskEvaluation.event.user.id A string that specifies the user ID associated with the risk evaluation. If the user type is PING_ONE, the user name is filled automatically according to the user ID. If the user does not exist in PING ONE, the step produces an error. If the user type is EXTERNAL, the user name should be added so that it displays in the dashboards; if the user name is not provided, the user ID is shown. This is a required property.
riskEvaluation.event.sharingType A string that specifies associated device sharing type. Options are UNSPECIFIED, SHARED, and PRIVATE.
riskEvaluation.event.browser.userAgent A string that specifies the user agent of the browser that triggered the flow. The placeholder, ${flow.inputs.headers.user-agent}, is recommended for browser-based flows.
riskEvaluation.event.origin A string that specifies the calling service.

The step returns the risk level of the transaction, which can be evaluated as HIGH, MEDIUM, or LOW. The following properties are returned for the HIGH, MEDIUM, or LOW risk levels.

The following properties are always returned in the risk evaluation.

Output property Description
riskEvaluation.id A string that specifies the ID of risk evaluation.
riskEvaluation.riskPolicySet.id A string that specifies the ID of risk policy set used for risk evaluation.
riskEvaluation.riskPolicySet.name A string that specifies the name of risk policy set used for risk evaluation.
riskEvaluation.result.value A string that specifies the risk result custom value.
riskEvaluation.details.ipAddressReputation An object that specifies the risk associated with IP address reputation.
riskEvaluation.details.ipAddressReputation.score An integer that specifies the risk associated with IP address reputation, expressed as a number between 0 and 100.
riskEvaluation.details.ipAddressReputation.level A string that specifies the risk level associated with IP address reputation. Options are HIGH, MEDIUM, or LOW.
riskEvaluation.details.anonymousNetworkDetected A boolean that specifies whether the IP is associated with an anonymous network.
riskEvaluation.details.country A string that specifies the country where the flow originated, according to the IP address.
riskEvaluation.details.impossibleTravel A boolean that specifies whether the velocity required to move between the user's previous successful location to its current inferred location is too large.

The following properties are returned in the risk evaluation only for environments with data consent enabled.

Output property Description
riskEvaluation.details.ipVelocityByUser.level A string that specifies the risk associated with IP velocity by user. Options are HIGH, MEDIUM, or LOW.
riskEvaluation.details.ipVelocityByUser.reason A string that specifies the reason for the risk associated with IP velocity by user.
riskEvaluation.details.ipVelocityByUser.threshold An object that provides information about the threshold used to determine the IP velocity level.
riskEvaluation.details.ipVelocityByUser.threshold.source A string that specifies the source used to calculate the threshold.
riskEvaluation.details.ipVelocityByUser.threshold.high A number that specifies whether the user accessed more than this number of IPs during the past hour. If so, the user is flagged as having HIGH IP velocity.
riskEvaluation.details.ipVelocityByUser.threshold.medium A number that specifies whether the user accessed more than this number of IPs during the past hour. If so, the user is flagged as having MEDIUM IP velocity.
riskEvaluation.details.ipVelocityByUser.threshold.calculatedAt A string that specifies date and time at which the threshold was calculated.
riskEvaluation.details.ipVelocityByUser.threshold.expiresAt A string that specifies date and time at which the threshold will expire and be re-calculated.
riskEvaluation.details.ipVelocityByUser.velocity.distinctCount An integer that specifies the distinct count of IPs accessed by the user in the previous seconds specified by the during property.
riskEvaluation.details.ipVelocityByUser.velocity.during An integer that specifies the number of seconds to use in determining the distinctCount value.
riskEvaluation.details.userVelocityByIp.level A string that specifies the risk associated with user velocity by IP. Options are HIGH, MEDIUM, or LOW.
riskEvaluation.details.userVelocityByIp.reason A string that specifies the reason for the risk associated with user velocity by IP.
riskEvaluation.details.userVelocityByIp.threshold An object that provides information about the threshold used to determine the user velocity level.
riskEvaluation.details.userVelocityByIp.threshold.high A number that specifies whether the IP was accessed by more than this number of users during the past hour. If so, it is flagged as having HIGH user velocity.
riskEvaluation.details.userVelocityByIp.threshold.medium A number that specifies whether the IP was accessed by more than this number of users during the past hour. If so, it is flagged as having MEDIUM user velocity.
riskEvaluation.details.userVelocityByIp.threshold.calculatedAt A string that specifies date and time at which the threshold was calculated.
riskEvaluation.details.userVelocityByIp.threshold.expiresAt A string that specifies date and time at which the threshold will expire and be re-calculated.
riskEvaluation.details.userVelocityByIp.velocity.distinctCount An integer that specifies the distinct count of users that accessed the IP in the previous seconds specified by the during property.
riskEvaluation.details.userVelocityByIp.velocity.during An integer that specifies the number of seconds to use in determining the distinctCount value.
riskEvaluation.details.userRiskBehavior.level A string that specifies the risk associated with user risk behavior. Options are HIGH, MEDIUM, or LOW.
riskEvaluation.details.userRiskBehavior.reason A string that specifies the reason for the risk associated with user risk behavior.
riskEvaluation.details.userBasedRiskBehavior.level A string that specifies the risk associated with user-based risk behavior. Options are HIGH, MEDIUM, or LOW.
riskEvaluation.details.userBasedRiskBehavior.reason A string that specifies the reason for the risk associated with user-based risk behavior.
Step properties used with flow executions
Flow state Description
PROFILE_DEVICE A flow status that prompts for a device profile action. The action is initiated only if the value of the profileDevice configuration property is set to true.
Links Description
profile.device The link to initiate an action to set the device profile. The action must provide a value for the browserFingerprint property and specify application/vnd.pingidentity.device.profile+json as the custom content type.
Parameters Description
browserFingerprint An object that specifies the browser fingerprint attributes.

Create User

This step type creates a new user in PingOne.

Step properties used with flow definitions
Configuration schema property Description
population.id A string that specifies the population ID to associate with the new user. This is a required property.
lifecycle.status A string that specifies the account lifecycle of the newly created user. Options are ACCOUNT_OK, and VERIFICATION_REQUIRED. When this step is used in conjunction with the VERIFY_ACCOUNT step, the status value is typically set to the VERIFICATION_REQUIRED flow state without sending a verification code.
Input property Description
user An object that specifies the user to create. The new user's properties are derived dynamically from non read-only attributes of the environment's schema at configuration time.

The following properties are returned for the SUCCEEDED result.

Output property Description
{{userProperties}} An object that specifies the flow output. Properties are dynamically derived from the environment's schema at configuration time.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the CREATE_USER step type.
Parameters Description
There are no flow action parameters associated with the CREATE_USER step type.

Form

This step type prompts the end user to submit a custom form. The step might include additional results for any buttons on the form.

Step properties used with flow definitions
Configuration schema property Description
form.id A string that specifies the form ID for the form to submit to the form manager service. This is a required property.
Input property Description
formData An object that specifies the context data used to render the form and pre-fill fields. Properties are derived from the selected form and retrieved from the form manager service at configuration time.

The following properties are returned for the SUBMITTED result.

Output property Description
form.id A string that specifies the form ID.
form.name A string that specifies the form name.
formData An object that encapsulates the submitted form data. Properties are derived from the selected form and retrieved from the form manager service at configuration time.
Step properties used with flow executions
Flow state Description
FORM_REQUIRED A flow status that requires the user to submit a form.
Flow state response schema property Description
form.id A string that specifies the ID of the form.
{{formDataProperties}} The properties required by the form.
Links Description
form.submit The link to initiate the form submit action. The action must specify application/vnd.pingidentity.form.submit+json as the custom content type.
Parameters Description
{{formDataProperties}} The properties required by the form.
Links Description
form.action The link to specify the form action. The action must specify application/vnd.pingidentity.form.action+json as the custom content type.
Parameters Description
key The key of the form field that was clicked.

Identity Provider

This step type delegates user authentication to an external identity provider.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the IDENTITY_PROVIDER_AUTHENTICATION step type.
Input property Description
identityProvider.id A string that specifies the external identity provider's ID. This is a required property.
identityProvider.loginHint A string that specifies the login identifier to the identity provider.
identityProvider.acrValues An array that designates the names of the authentication policies applicable to the authorization request.

The following properties are returned for the ACCOUNT_LINKED result.

Output property Description
externalAuthentication.id A string that specifies the ID for the external authentication transaction. This is a required property.
externalAuthentication.externalId A string that specifies the unique identifier for the user returned by the external identity provider. This is a required property.
externalAuthentication.identityProvider.id A string that specifies the ID for the external identity provider. This is a required property.
externalAuthentication.attributes An object that specifies the mapped attributes returned by the external identity provider.
linkedUser An object that specifies the user linked to the external account from the extrnal identity provider. Properties are dynamically derived from the environment's schema at configuration time. This is a required property.

The following properties are returned for the ACCOUNT_LINKING_REQUIRED result.

Output property Description
externalAuthentication.id A string that specifies the ID for the external authentication transaction. This is a required property.
externalAuthentication.externalId A string that specifies the unique identifier for the user returned by the external identity provider. This is a required property.
externalAuthentication.identityProvider.id A string that specifies the ID for the external identity provider. This is a required property.
externalAuthentication.attributes An object that specifies the mapped attributes returned by the external identity provider.
mappedUser An object that specifies the user with mapped attribute values that can be used to pre-fill an external identity provider registration form. This is a required property.
matchingUsers An object that specifies the list of existing users that may be candidates for linking to the external account. These users are matched based on mapped attribute values.
user[].{{properties}} An object that specifies the flow output. User properties are dynamically derived from the environment's schema at configuration time.
Step properties used with flow executions
Properties for the EXTERNAL_AUTHENTICATION_REQUIRED flow state
Flow state Description
EXTERNAL_AUTHENTICATION_REQUIRED A flow status that prompts the user to authenticate with an external identity provider to continue the flow.
Flow state response schema property Description
authenticate.href A string that specifies the browser URL redirect to authenticate with the external identity provider.
Flow state embedded resource property Description
identityProvider.name A string that specifies the identity provider's name.
identityProvider.type A string that specifies the identity provider's type. Options are FACEBOOK, GOOGLE, LINKEDIN, OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, and SAML.
Flow execution actions
externalAuthentication.check action
Links Description
externalAuthentication.check The link to initiate an action to check the external authentication ID. The action must provide a value for the id property and specify application/vnd.pingidentity.externalAuthentication.check+json as the custom content type in the request.
Parameters Description
externalAuthentication.id A string that specifies the external authentication ID. This is a required property.

Invoke External Service

This step type invokes an external service request. Note that the input properties in the request and the output properties in the response are generated dynamically based on the input and output schemas defined in the external service configuration.

Step properties used with flow definitions
Configuration schema property Description
externalService.id A string that specifies the ID of the external service, which is the target of the request.
request.id A string that specifies the request configuration to execute.
Input property Description
{someRequestProperty} The input properties are dynamically generated based on list of inputs on request configuration.

The following properties are returned for the INVOCATION_OUTPUT result.

Output property Description
someOutputProperty The output properties are populated dynamically if if output schema is provided.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the EXTERNAL_SERVICE_INVOKE step type.
Parameters Description
There are no flow action parameters associated with the EXTERNAL_SERVICE_INVOKE step type.

MFA Auto Enrollment

This step type pairs an MFA offline device automatically with the user account during MFA enrollment.

Step properties used with flow definitions
Configuration schema property Description
sms.enabled A boolean that that when set to true auto enrolls an SMS device.
sms.mode A string that specifies the available modes to auto enroll an SMS device. Options are CREATE, OVERRIDE, and REPLACE. The default value is CREATE.
voice.enabled A boolean that that when set to true auto enrolls a voice device.
voice.mode A string that specifies the available modes to auto enroll a voice device. Options are CREATE, OVERRIDE, and REPLACE. The default value is CREATE.
email.enabled A boolean that that when set to true auto enrolls an email device.
email.mode A string that specifies the available modes to auto enroll an email device. Options are CREATE, OVERRIDE, and REPLACE. The default value is CREATE.
Input property Description
user.id A string that specifies the user ID of the user account. This is a required property.
user.sms.mobilePhone A string that specifies the phone number of the SMS device. This is a required property.
user.sms.oldMobilePhone A string that specifies the phone number of the old SMS device. This is a required property.
user.voice.mobilePhone A string that specifies the phone number of the voice device. This is a required property.
user.voice.oldMobilePhone A string that specifies the phone number of the old voice device. This is a required property.
user.email.email A string that specifies the email address of the email device. This is a required property.
user.email.oldEmail A string that specifies the email address of the old email device. This is a required property.

The following properties are returned for the ENROLLED result.

Output property Description
devices.sms.id A string that specifies the ID of the SMS device.
devices.sms.type A string that specifies the device type.
devices.sms.phone A string that specifies the phone number associated with the device.
devices.voice.id A string that specifies the ID of the voice device.
devices.voice.type A string that specifies the device type.
devices.voice.phone A string that specifies the phone number associated with the device.
devices.email.id A string that specifies the ID of the email device.
devices.email.type A string that specifies the device type.
devices.email.email A string that specifies the email address associated with the device.

The following properties are returned for the NOT_APPLICABLE result.

Output property Description
There are no output properties for the NOT_APPLICABLE result.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the MFA_AUTO_ENROLLMENT step type.
Parameters Description
There are no flow action parameters associated with the MFA_AUTO_ENROLLMENT step type.

MFA Challenge

This step type performs a multi-factor authentication in PingOne. The step returns a SUCCEEDED result.

Step properties used with flow definitions
Configuration schema property Description
deviceAuthenticationPolicy.id A string that specifies the device authentication policies to use during authentication. This is a required property.
deviceSelection A string that specifies the device selection mode. Options are DEFAULT_TO_FIRST, and PROMPT_TO_SELECT. The default value is DEFAULT_TO_FIRST. This is a required property.
template.name A string that specifies the name of the notification template used for user notifications. Options are STRONG_AUTHENTICATION, and TRANSACTION. This is a required property.
template.variant A string that specifies the notification template variant.
useDefaultPolicy A boolean that, when set to true, specifies that the default device authentication policy for the environment is used during MFA evaluation.
Input property Description
user.id A string that specifies the user ID. This is a required property.
template.locale A string that specifies the notifications template locale. This is a required property.
template.variables An object that specifies the notifications template variables.
webauthn.compatibility A string that specifies the webauthn compatibility.
mobile.clientContext An object that specifies the mobile client context.
mobile.payload A string that specifies the mobile payload. The default value is ${flow.inputs.parameters.mobilePayload}.
application.id A string that specifies the application ID. The default value is ${flow.inputs.parameters.applicationId}.
session.id A string that specifies the session ID. The default value is ${flow.inputs.parameters.sessionId}.
userAgent A string that specifies the user agent of the browser that triggered the flow. The default value is ${flow.inputs.headers.user-agent}.

The following properties are returned for the SUCCEEDED result.

Output property Description
device.id A string that specifies the device ID.
device.nickname A string that specifies the device nickname.
device.type A string that specifies the device type. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY.
amr An array that specifies the authentication methods.
Step properties used with flow executions
Properties for the DEVICE_SELECTION_REQUIRED flow state
Flow state Description
DEVICE_SELECTION_REQUIRED A flow status that prompts the user to select an available device to use for authentication.
Flow state response schema property Description
deviceAuthentication An object that specifies the device authentication parameters.
Properties for the OTP_REQUIRED flow state
Flow state Description
OTP_REQUIRED A flow status that requires the user to complete a multi-factor authentication action using a one-time passcode.
Flow state response schema property Description
devices An object that specifies the user devices available that can be used to complete the multi-factor authentication action.
deviceAuthentication.authSession.type A string that specifies the type of authentication session.
deviceAuthentication.authSession.id A string that specifies the authentication session ID.
deviceAuthentication.selectedDevice.id A string that specifies the ID of the device used for authentication.
deviceAuthentication.user.id A string that specifies the user ID of the authenticating user.
Properties for the ASSERTION_REQUIRED flow state
Flow state Description
ASSERTION_REQUIRED A flow status that prompts the user to activate the WebAuthn device to finalize the authentication process.
Flow state response schema property Description
devices An object that specifies the available devices that can be used for activation.
deviceAuthentication.authSession.type A string that specifies the type of authentication session.
deviceAuthentication.authSession.id A string that specifies the authentication session ID.
deviceAuthentication.selectedDevice.id A string that specifies the ID of the device used for authentication.
deviceAuthentication.user.id A string that specifies the user ID of the authenticating user.
Properties for the PUSH_CONFIRMATION_REQUIRED flow state
Flow state Description
PUSH_CONFIRMATION_REQUIRED A flow status that results when a push was sent to a native device to confirm the authentication.
Flow state response schema property Description
devices An object that specifies the available devices that can be used for activation.
deviceAuthentication.authSession.type A string that specifies the type of authentication session.
deviceAuthentication.authSession.id A string that specifies the authentication session ID.
deviceAuthentication.selectedDevice.id A string that specifies the ID of the device used for authentication.
deviceAuthentication.user.id A string that specifies the user ID of the authenticating user.
Properties for the PUSH_CONFIRMATION_TIMED_OUT flow state
Flow state Description
PUSH_CONFIRMATION_TIMED_OUT A flow status that specifies that a push was sent to a native device, but the native device did not answer the push during the allowed timeframe.
Flow state response schema property Description
devices An object that specifies the available devices that can be used for activation.
deviceAuthentication.authSession.type A string that specifies the type of authentication session.
deviceAuthentication.authSession.id A string that specifies the authentication session ID.
deviceAuthentication.selectedDevice.id A string that specifies the ID of the device used for authentication.
deviceAuthentication.user.id A string that specifies the user ID of the authenticating user.
Flow execution actions
Device device.select action
Links Description
device.select The link to initiate an action to specify an MFA device to associate with the user. The action must provide a value for the type property and specify application/vnd.pingidentity.device.select+json as the custom content type in the request.
Parameters Description
device.id A string that specifies the ID of the selected device. This is a required property.
compatibility A string that specifies the browser WebAuthn compatibility. Options are FULL, SECURITY_KEY_ONLY, and NONE.
Device otp.check action
Links Description
otp.check The link to initiate an action to validate the one-time passcode received by the selected device. The action must specify application/vnd.pingidentity.otp.check+json as the custom content type in the request.
Parameters Description
otp A string that specifies the one-time passcode. This is a required property.
Device assertion.check action
Links Description
assertion.check The link to initiate an action to validate the assertion received by the selected FIDO2 device. The action must specify application/vnd.pingidentity.assertion.check+json as the custom content type in the request.
Parameters Description
assertion A string that specifies the WebAuthn Assertion response. This is a required property.
compatibility A string that specifies the browser WebAuthn compatibility. Options are FULL, SECURITY_KEY_ONLY, and NONE.
origin A string that specifies the full URL of the calling service. This is a required property.

MFA Enrollment

This step type pairs an MFA device with the user account during MFA enrollment. The step returns either the ENROLLED or SKIPPED result.

Step properties used with flow definitions
Configuration schema property Description
useDefaultPolicy A boolean that when set to true specifies that the environment's default device authentication policy is used during MFA evaluation. This is a required property.
deviceAuthenticationPolicy.id A string that specifies the ID device authentication policy to use during authentication. This is a required property only in cases in which the useDefaultPolicy property is set to false.
template.variant A string that specifies the notification template variant.
Input property Description
user.id A string that specifies the user ID of the user account from the identity provider. This is a required property.
user.email A string that specifies the user's email address.
user.mobilePhone A string that specifies the user's mobile phone number.
webauthn.compatibility A string that specifies the webauthn compatibility. Options are FULL, SECURITY_KEY_ONLY, and NONE.
template.locale A string that specifies the notification template locale.
template.variables An object that specifies the notification template variables.

The following properties are returned for the ENROLLED result.

Output property Description
device.id A string that specifies the device ID.
device.type A string that specifies the device type. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY.

The following properties are returned for the SKIPPED result.

Output property Description
There are no output properties for the SKIPPED result.
Step properties used with flow executions
Properties for the DEVICE_ENROLLMENT_REQUIRED flow state
Flow state Description
DEVICE_ENROLLMENT_REQUIRED A flow status that prompts the user to either enroll a device or skip the enrollment process.
Flow state response schema property Description
email A string that specifies the user email provided in the step inputs.
mobilePhone A string that specifies the user mobile phone number provided in the step inputs.
allowedtypes An array that specifies the allowed device types for pairing. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY.
mfaSettings An object that specifies the environment's MFA settings.
applications An array that specifies the environment applications.
Properties for the ACTIVATION_REQUIRED flow state
Flow state Description
ACTIVATION_REQUIRED A flow status that prompts the user to activate the offline device to finalize the enrollment process.
Flow state response schema property Description
device An object that specifies the user device pending for activation. The device properties shown depend on the device type.
Properties for the PAIRING_REQUIRED flow state
Flow state Description
PAIRING_REQUIRED A flow status that prompts the user to pair the mobile device to finalize the mobile enrollment process. The client will have to poll the HAL self link (/{envID}/flowExecutions/{flowExecutionID}) to verify the pairing.
Flow state response schema property Description
device An object that specifies the user device pending for activation. The device properties shown depend on the device type.
pairingKey.code A string that specifies the mobile pairing key code, used to finalize the mobile enrollment process.
Properties for the MOBILE_PAIRING_FAILURE flow state
Flow state Description
MOBILE_PAIRING_FAILURE A flow status that results when mobile pairing has failed. This status returns the error code and the mobile pairing error details.
Flow state response schema property Description
error An object that specifies the error details.
error.code A string that specifies the error code.
error.message A string that specifies the error message.
Flow execution actions
Device create device.create action
Links Description
device.create The link to initiate an action to specify an MFA device to associate with the user. The action must provide a value for the type property and specify application/vnd.pingidentity.device.create+json as the custom content type in the request.
Parameters Description
type A string that specifies the device type. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY. This is a required property.
nickname A string that specifies the device nickname.
email A string that specifies the user's email address.
phone A string that specifies the user's phone number.
application.id A string that specifies the associated application ID, which is required for pairing with devices of type MOBILE.
rp.id A string that specifies an RP ID, which is based on a host's domain name.
rp.name A string that specifies a human-readable name for the user account.
Device activate device.activate action
Links Description
device.activate The link to initiate an action to activate an MFA device. The action must specify application/vnd.pingidentity.device.activate+json as the custom content type in the request.
Parameters Description
otp A string that specifies the one-time passcode.
attestation A string that specifies the FIDO2 attestation.
origin A string that specifies the calling service.
Device skip device.skipEnrollment action
Links Description
device.skipEnrollment The link to skip device enrollment. This action can be used only if device registration is configured to allow skipping. The action must specify the application/vnd.pingidentity.device.skipEnrollment+json as the custom content type in the request.
Parameters Description
There are no parameters required for the device.skipPairing action.
Device delete device.delete action
Links Description
device.delete The link to delete the device registration process. This action must specify the application/vnd.pingidentity.device.delete+json as the custom content type in the request.
Parameters Description
There are no parameters required for the device.delete action.
Resend OTP otp.resend action
Links Description
otp.resend The link to resend the OTP to complere the device registration process for SMS, email, and voice devices. This action must specify the application/vnd.pingidentity.otp.resend+json as the custom content type in the request.
Parameters Description
There are no parameters required for the otp.resend action.

MFA Mobile Auto Enrollment

This step type pairs an MFA mobile device with the user account during MFA enrollment.

Step properties used with flow definitions
Configuration schema property Description
{{properties}} An object that specifies the properties that are dynamically derived at configuration time.
Input property Description
user.id A string that specifies the user ID of the user account. This is a required property.
application.id A string that specifies the application ID. This is a required property.
mobile.payload A string that specifies the mobile payload. This is a required property.

The following properties are returned for the ENROLLMENT_INITIATED result.

Output property Description
enrollment An object that specifies the enrollment data created by the auto enrollment flow.

The following properties are returned for the NOT_APPLICABLE result.

Output property Description
There are no output properties for the NOT_APPLICABLE result.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the MFA_MOBILE_AUTO_ENROLLMENT step type.
Parameters Description
There are no flow action parameters associated with the MFA_MOBILE_AUTO_ENROLLMENT step type.

Password Check

This step type specifies an action to check a PingOne user's password.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the USER_PASSWORD_CHECK step.
Input property Description
user.id A string that specifies the user ID of the user account associated with the password check action. This is a required property.
user.password A string that specifies the user's password to check. This is a required property.

The following properties are returned for the PASSWORD_VALID result.

Output property Description
passwordState.user.id A string that specifies the user's password state.
passwordState.passwordPolicy.id A string that specifies the password policy ID.
passwordState.status A string that specifies the current status of the password.
passwordState.lastChanged The date and time the password was last changed.
passwordState.warnings.expires A string that specifies the date and time the password expires.

The following properties are returned for the PASSWORD_EXPIRED result.

Output property Description
passwordState.user.id A string that specifies the user's password state.
passwordState.passwordPolicy.id A string that specifies the password policy ID.
passwordState.status A string that specifies the current status of the password.
passwordState.lastChangedAt The date and time the password was last changed.
passwordState.warnings.expires A string that specifies the date and time the password expires.

The following properties are returned for the MUST_CHANGE_PASSWORD result.

Output property Description
passwordState.user.id A string that specifies the user's password state.
passwordState.passwordPolicy.id A string that specifies the password policy ID.
passwordState.status A string that specifies the current status of the password.
passwordState.lastChangedAt The date and time the password was last changed.
passwordState.warnings.expires A string that specifies the date and time the password expires.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the USER_PASSWORD_CHECK step type.
Parameters Description
There are no flow action parameters associated with the USER_PASSWORD_CHECK step type.

Password Recover

This step type verifies an account by prompting for a verification code sent to the user through email. The step returns a VERIFIED result after the verification code is submitted successfully by the end user. The step can also return a SKIPPED result if the user chooses to skip the account verification step.

Step properties used with flow definitions
Configuration schema property Description
allowSkip A boolean that specifies whether the user is allowed to skip account verification.
Input property Description
userId A string that specifies the user ID of the user account to verify. This is a required property.

The following properties are returned for the VERIFIED result.

Output property Description
There are no output properties for the VERIFIED result.

The following properties are returned for the SKIPPED result.

Output property Description
There are no output properties for the SKIPPED result.
Step properties used with flow executions
Flow state Description
VERIFICATION_CODE_REQUIRED A flow status prompts the user to complete an account verification action. The user can submit a verification code to verify the account, have another verification code sent, or optionally skip verification if the step is configured to allow skipping.
Account verification user.verify action
Links Description
user.verify The link to initiate an action to send a verification code to the user. The action must provide a value for the verificationCode property and specify application/vnd.pingidentity.user.verify+json as the custom content type.
Parameters Description
verificationCode A string that specifies the verification code sent to the user.
Account verification user.sendVerificationCode action
Links Description
user.sendVerificationCode The link to initiate an action to send a verification code to the user. The action must provide a value for the verificationCode property and specify application/vnd.pingidentity.user.sendVerificationCode+json as the custom content type.
Parameters Description
There are no parameters required for the user.sendVerificationCode action.
Account verification user.skipVerification action
Links Description
user.skipVerification The link to skip account verification. This action can be used only if account verification is configured to allow skipping. The action must specify the application/vnd.pingidentity.user.skipVerification+json as the custom content type.
Parameters Description
There are no parameters required for the user.skipVerification action.

PingID Authentication for Windows Passwordless Login

This step type authenticates users with PingID. It is used for passwordless login on Windows devices.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the PINGID_AUTHENTICATION_FOR_WINDOWS_PASSWORDLESS_LOGIN step type.
Input property Description
user.username A string that specifies the user name as it is defined in PingID.

The following properties are returned for the SUCCEEDED result.

Output property Description
pingIdDevice.id A string that specifies the PingID device ID.
Step properties used with flow executions
Flow state Description
There is no flow status associated with the PINGID_AUTHENTICATION_FOR_WINDOWS_PASSWORDLESS_LOGIN step type.
Links Description
device.select The link to initiate the PingID device select action. The action must specify application/vnd.pingidentity.device.select+json as the custom content type in the request.
Parameters Description
device.id A string that specifies the selected PingID device ID.
Links Description
authentication.poll The link to specify an action to check the current authentication status. The action must specify application/vnd.pingidentity.authentication.poll+json as the custom content type in the request.
Parameters Description
There are no parameters for the authentication.poll action.
Links Description
otp.check The link to initiate an action to validate the one-time passcode. The action must specify application/vnd.pingidentity.otp.check+json as the custom content type in the request.
Parameters Description
otp A string that specifies the offline device one-time passcode.
Links Description
certificate.create The link to initiate an action to create a certificate. The action must specify application/vnd.pingidentity.certificate.create+json as the custom content type in the request.
Parameters Description
csr A string that specifies the certificate signing request, which is Base-64 encoded PEM format that contains information that is included in the certificate.
Links Description
certificate.create The link to initiate an action to create a certificate. The action must specify application/vnd.pingidentity.certificate.create+json as the custom content type in the request.
Parameters Description
csr A string that specifies the certificate signing request, which is Base-64 encoded PEM format that contains information that is included in the certificate.
pin A string that specifies the PIN that protects the certificate's private key.
Links Description
certificate.readPin The link to initiate an action to retrieve the PIN code that protects the certificate's private key. The action must specify application/vnd.pingidentity.certificate.readPin+json as the custom content type in the request.
Parameters Description
certificate.id A string that specifies the certificate ID.
Links Description
authentication.resume The link to initiate an action to complete the authentication. The action must specify application/vnd.pingidentity.authentication.resume+json as the custom content type in the request.
Parameters Description
There are no parameters for the authentication.resume action.

Read User

This step type reads user account data for the user specified by the ID in the input property.

Step properties used with flow definitions
Configuration schema property Description
{{properties}} An object that specifies the user properties. Properties are dynamically derived from the environment's schema at configuration time.
Input property Description
user.id A string that specifies the user ID. This is a required property.

The following properties are returned for the SUCCEEDED result.

Output property Description
{{userProperties}} An object that specifies the flow output. Properties are dynamically derived from the environment's schema at configuration time.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the USER_READ step type.
Parameters Description
There are no flow action parameters associated with the USER_READ step type.

Reset Password

This step type specifies an action to reset a user's password using the current password.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the USER_PASSWORD_RESET step.
Input property Description
user.id A string that specifies the user ID of the user account associated with the password reset action. This is a required property.
currentPassword A string that specifies the user's current password. This is a required property.
newPassword A string that specifies the new password for the user account. This is a required property.

The following properties are returned for the SUCCEEDED result.

Output property Description
passwordState.user.id A string that specifies the user's password state.
passwordState.passwordPolicy.id A string that specifies the password policy ID.
passwordState.status A string that specifies the current status of the password.
passwordState.lastChanged The date and time the password was last changed.
passwordState.warnings.expires A string that specifies the date and time the password expires.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the USER_PASSWORD_RESET step type.
Parameters Description
There are no flow action parameters associated with the USER_PASSWORD_RESET step type.

Send Recovery Code

This step type specifies an action to send a recovery code to recover a forgotten password.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the USER_PASSWORD_SEND_RECOVERY_CODE step.
Input property Description
user.id A string that specifies the user ID of the user account associated with the send recovery code action. This is a required property.

The following properties are returned for the SUCCEEDED result.

Output property Description
passwordState.user.id A string that specifies the user's password state.
passwordState.passwordPolicy.id A string that specifies the password policy ID.
passwordState.status A string that specifies the current status of the password.
passwordState.lastChanged The date and time the password was last changed.
passwordState.warnings.expires A string that specifies the date and time the password expires.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the USER_PASSWORD_SEND_RECOVERY_CODE step type.
Parameters Description
There are no flow action parameters associated with the USER_PASSWORD_SEND_RECOVERY_CODE step type.

Terminate Flow

This step type ends the flow and returns an error message.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration properties for the TERMINATE_FLOW step type.
Input property Description
error.code A string that specifies the unique error code for the error. This is a required property.
error.message A string that specifies the message describing the error. The error message can include HTML formatted text such as links, headings, lists, and line breaks. This is a required property.
Output property Description
There are no output properties for the TERMINATE_FLOW step type.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the TERMINATE_FLOW step type.
Parameters Description
There are no flow action parameters associated with the TERMINATE_FLOW step type.

Update User

This step type specifies an action to update the user record in PingOne.

Step properties used with flow definitions
Configuration schema property Description
There are no configuration schema properties for the USER_PATCH step.
Input property Description
user.id A string that specifies the user ID of the user account associated with the update action. This is a required property.

The following properties are returned for the SUCCEEDED result.

Output property Description
user.{{properties}} The updated user record. User properties are dynamically derived from the environment's schema at configuration time.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this step type.
Links Description
There are no flow actions associated with the USER_PATCH step type.
Parameters Description
There are no flow action parameters associated with the USER_PATCH step type.

User Lookup

This step type that specifies a user lookup action to determine the authentication authority. The response returns either a PING_ONE_USER_MATCHED or IDENTITY_PROVIDER_USER_MATCHED result.

Step properties used with flow definitions
Configuration schema property Description
matchAttributes.[] An array that specifies the attributes to match against the provided identifier when searching for a user in the directory. Only unique attributes can be specified, and the attributes are searched in order, returning the first user that matches. If no match is found, the action returns an error. The default attribute is username. This is a required property.
matchPingOneUsersOnly A boolean that specifies whether to match only users whose authentication authority is PingOne. This property defaults to false if it is not set.
Input property Description
identifier A string that specifies the identifier to use when searching for the user. This is a required property.

The following properties are returned for the PING_ONE_USER_MATCHED result.

Output property Description
user An object that specifies the attributes of the matched user. Properties are dynamically derived from the environment's schema at configuration time.

The following properties are returned for the IDENTITY_PROVIDER_USER_MATCHED result.

Output property Description
user An object that specifies the attributes of the matched user. Properties are dynamically derived from the environment's schema at configuration time.
Step properties used with flow executions
Flow state Description
There is no flow status associated with this action.
Links Description
There are no flow actions associated with the USER_LOOKUP step type.
Parameters Description
There are no flow action parameters associated with the USER_LOOKUP step type.

Verify Email

This step type verifies an account by prompting for a verification code sent to the user through email. The step returns a VERIFIED result after the verification code is submitted successfully by the end user. The step can also return a SKIPPED result if the user chooses to skip the account verification step.

Step properties used with flow definitions
Configuration schema property Description
allowSkip A boolean that specifies whether the user is allowed to skip account verification.
Input property Description
userId A string that specifies the user ID of the user account to verify. This is a required property.

The following properties are returned for the VERIFIED result.

Output property Description
There are no output properties for the VERIFIED result.

The following properties are returned for the SKIPPED result.

Output property Description
There are no output properties for the SKIPPED result.
Step properties used with flow executions
Flow state Description
VERIFICATION_CODE_REQUIRED A flow status prompts the user to complete an account verification action. The user can submit a verification code to verify the account, have another verification code sent, or optionally skip verification if the step is configured to allow skipping.
Account verification user.verify action
Links Description
user.verify The link to initiate an action to send a verification code to the user. The action must provide a value for the verificationCode property and specify application/vnd.pingidentity.user.verify+json as the custom content type.
Parameters Description
verificationCode A string that specifies the verification code sent to the user.
Account verification user.sendVerificationCode action
Links Description
user.sendVerificationCode The link to initiate an action to send a verification code to the user. The action must provide a value for the verificationCode property and specify application/vnd.pingidentity.user.sendVerificationCode+json as the custom content type.
Parameters Description
There are no parameters required for the user.sendVerificationCode action.
Account verification user.skipVerification action
Links Description
user.skipVerification The link to skip account verification. This action can be used only if account verification is configured to allow skipping. The action must specify the application/vnd.pingidentity.user.skipVerification+json as the custom content type.
Parameters Description
There are no parameters required for the user.skipVerification action.

Forms

The forms API, which supports the form builder interface in the PingOne Admin Console, provides tools for administrators to create custom forms presented to users during the authentication workflow. This capability allows administrators to:

  • Define the interactive fields and the corresponding data to be collected during a registration or sign-on flow, which could include text inputs, checkboxes, dropdowns, and radio buttons with the potential for dynamic options or dynamically static options (dropdowns with options saved as part of the form or as input for an argument).

  • Define the user experience that they want to deliver to the customer, such as field ordering, labeling, control over input validation and error feedback, and support for contextual or formatting items such as text (headers, explanatory text) images, and dividers.

The forms API provides endpoints to create, read, update, and delete form builder resources.

Forms category types

The API allows the following form types:

  • REGISTRATION

    A registration form that allows administrators to configure the controls and the information gathered during the registration flow. This form type allows form fields that do not map directly to PingOne user schema properties.

  • SELF_SERVICE

    A self-service form that allows administrators to configure the controls and the information gathered during a self-service flow. All fields in the self-service form must be associated with PingOne user schema properties.

  • PROGRESSIVE_PROFILING

    A custom registration form that prompts the user for additional information during the registration or sign-on flow. All fields in the progressive profiling form must be associated with PingOne user schema properties.

  • CUSTOM

    A custom registration form that allows form fields that do not map directly to PingOne user schema properties. For example, the form could include radio buttons with options of “employee” or “contractor” that the flow manager processes to direct the user to the next relevant form.

Forms data model
Property Description
created The time the resource was created.
category A string that specifies the type of custom-defined form. Options are REGISTRATION, SELF_SERVICE, PROGRESSIVE_PROFILING, and CUSTOM. The CUSTOM and REGISTRATION form types allow the form to be built with fields that do not map specifically to the PingOne directory attributes. This is a required property.
cols An integer that specifies the number of columns in the form.
components An object that specifies the form configuration elements.
description A string that specifies the description of the population.
fieldTypes A read-only that specifies the list of the FormField types in the form. Options are TEXT, SUBMIT_BUTTON, FLOW_LINK, FLOW_BUTTON, and RECAPTCHA_V2.
id A string that specifies the resource’s unique identifier.
markOptional A boolean that specifies whether optional fields are highlighted in the rendered form. This is a required property.
markRequired A boolean that specifies whether required fields are highlighted in the rendered form. This is a required property.
modified The time the resource was last updated.
name A string that specifies the form name, which must be provided and must be unique within an environment. This is a required property.
Form components data model
Property Description
button A form button object that contains the button text. This is a required property.
button.text A string that specifies the form button text. This is a required property.
fields A list of form fields that specifies the form fields that make up the form. Options include text inputs, passwords, radio buttons, checkboxes, dropdowns, headers, and dividers. This is a required property.
FormField data model
  • FormElement represents a FormField of types TEXT, PASSWORD, RADIO, CHECKBOX, DROPDOWN.
  • FormItem represents a FormField of types DIVIDER, PARAGRAPH, EMPTY_FIELD, ERROR_DISPLAY.
  • FormElementPasswordVerify represents a FormField of type PASSWORD_VERIFY.
  • FormSubmit represents a FormField of type SUBMIT_BUTTON.
  • FormFlowLink represents FormField of type FLOW_LINK.
  • FormFlowButton represents a FormField of type FLOW_BUTTON.
  • FormRecaptchaV2 represents a FormField of type RECAPTCHA_V2.
  • FormQrCode represents a FormField of type QR_CODE.
Property Description
position An object containing field position information. This is a required property.
position.col An integer that specifies the column position of the field. This is a required property.
position.row An integer that specifies the row position of the field. This is a required property.
position.width An integer that specifies the width of the field.
type A string that specifies the type of the field. Options are TEXT, PASSWORD, PASSWORD_VERIFY, RADIO, CHECKBOX, DROPDOWN, DIVIDER, EMPTY_FIELD, TEXTBLOB, ERROR_DISPLAY, SUBMIT_BUTTON, FLOW_LINK, FLOW_BUTTON, RECAPTCHA_V2, and QR_CODE.
. This is a required property.
FormElement data model
Property Description
key A string that specifies the field unique key for the HTML name attribute. This is a required property.
label A string that specifies the field label. This is a required property.
layout A string that specifies layout attributes for radio button and checkbox fields. Options are HORIZONTAL or VERTICAL. This is a required property when the type is RADIO or CHECKBOX.
options An array of strings that specifies the unique list of options. This is a required property when the type is RADIO, CHECKBOX, or DROPDOWN.
required A boolean that specifies whether the field is required. This is a required property.
validation An object containing validation data for the field. This is a required property when the type is TEXT.
validation.regex A string that specifies a validation regular expression. The expression must be a valid regular expression string. This is a required property when the validation type is CUSTOM.
validation.type A string that specifies the validation type. Options are NONE and CUSTOM. This is a required property when the field type is TEXT.
validation.errorMessage A string that specifies the error message to be displayed when the field validation fails.
FormElementPasswordVerify data model

The FormElementPasswordVerify object is an extension of FormElement and contains all of the same fields in FormElement as well as those listed below.

Property Description
labelPasswordVerify A string that verifies password field label.
FormItem data model
Property Description
content A string that specifies the field content (for example, HTML when the field type is TEXTBLOB.
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.

READ Forms

READ One Form

CREATE Registration Form

CREATE Progressive Profiling Form

CREATE Self Service Form

CREATE Sign On Form

CREATE Identity Provider Sign On Form

CREATE Password Reset Form

CREATE Password Recovery User Lookup Form

CREATE Password Recovery Form

CREATE Custom Form

UPDATE Form

DELETE One Form

Forms: Recaptcha

The Recaptcha configuration API provides support for a Recaptcha V2 field in a form definition. It includes operations to read, update, and delete the environment's Recaptcha configuration.

Recaptcha V2 data model
Property Description
created The time the configuration was created.
environment.id A string that specifies the environment's unique identifier.
modified The time the configuration was last updated.
siteKey A string that specifies the public site key for the Recaptcha configuration provided by Google. This is a required property.
secretKey A string that specifies the confidential secret key for the Recaptcha configuration provided by Google. This is a required property.
Response codes
Code Message
200 Successful operation.
204 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.

READ Recaptcha Configuration

UPDATE Recaptcha Configuration

DELETE Recaptcha Configuration

Configuration Management

The Configuration Management service gives you a secure and flexible approach to automating (promoting) configurations across multiple environments, enabling the seamless creation, updating, and deletion of resources while supporting dynamic configurations through variable management. Resource dependencies are maintained, ensuring smooth cross-environment transitions and promotions. Auditing and reporting enhance oversight and compliance.

To use the Configuration Management service you need to have the Environment Admin role for at least two environments. The general workflow is:

  • Select configurations that you want to promote from one environment to another (generally, through development, testing, and production stages).
  • If desired, use promotion variables to dynamically substitute different property values for a configuration resource included in a promotion operation.
  • Execute the promotion plan returned by the Read One Promotion or Read All Promotions to move the configuration from the source environment to the target environment.

The Configuration Management service is comprised of these sub-services:

Resources requiring special handling

Certificates

Certificates are not a promotable resource in PingOne, however special handling of them is required for resources that reference them. Certificate references can be promoted in using either default certificates or through the use of promotion variables:

  • Default certificates

    When a configuration resource is using the default certificate as its signing key (a SAML application, for example), the application can be promoted, and will reference the default signing key existing in the target environment. Certificate rotation for the signing key can be done by setting a new default certificate in the target environment, and then promoting the configuration resource or resources using the default signing key in the source environment.

  • Certificates as promotion variables

    You can handle all certificate references other than default certificates using promotion variables. You'll need to create a promotion variable with the certificate ID in each environment. When the resource or resources referencing the certificate are promoted, the promotion operation will use the variable value to substitute the correct certificate in the target environment or environments. If there are other configuration resources that use the certificate, they will also use the correct certificate when any of these configuration resources are promoted to the same target environment or environments.

Attributes

You can promote individual attributes in the schema. However if you're promoting an application that references a custom attribute, the promotion plan will include all attributes in the schema. In this case, you can then exclude the unnecessary attributes by editing the promotion plan prior to starting the promotion operation.

Snapshots

A snapshot is a point in time representation of any configuration resource in PingOne. A snapshot is triggered when the request POST {{apiPath}}/environments/{{envID}}/snapshots is called. The configuration resource, and optionally all of its dependencies, are then stored by the Snapshot service. The snapshots are stored and indexed using the original identifier (ID) of the configuration resource. For example, an applications snapshot will be stored using the ID of the application. Subsequent calls to the request POST {{apiPath}}/environments/{{envID}}/snapshots for the same configuration resource generates a new version of the configuration resource each time the request is called. You can retrieve the version history of any configuration resource using the original identifier of the resource. You'll use the snapshot created for a configuration resource to promote (apply) the configuration resource from the source environment to another environment.

Snapshots data model

Property Type Required? Mutable? Description
baseResourceURL String Required Mutable The URL of the resource to use. The form is: "https://api.pingone.com/v1/environments/{{envId}}/{{resourceName}}/{{resourceId}}", where "resourceName" is the name of the configuration resource to snapshot.
createdAt Date N/A Read-only The date and time at which the resource was created (ISO 8601 format).
completedAt Date N/A Read-only The date and time at which the snapshot creation was completed (ISO 8601 format).
configuration Object N/A Read-only The JSON representation of the configuration resource. If the configuration resource has been deleted, this will be empty (null).
error String N/A Read-only If an error occurs while creating the snapshot, it's returned here.
id String Required Immutable The identifier of the configuration resource.
resourceId String Optional Mutable The identifier of the configuration resource.
resourceUrl String Optional Mutable The URL of the configuration resource.
referencedResources String[] Optional Mutable The list of identifiers for any dependent or referenced configuration resources. The dependent or referenced resources can be only one level down in the possible tree of such resources.
snapshotId String N/A Read-only The identifier of the snapshot.
startedAt Date N/A Read-only The date and time at which the snapshot creation was started (ISO 8601 format).
status String N/A Read-only The status of the snapshot creation process. This can be any one of: COMPLETE, WAITING, IN_PROGRESS, ERROR.
updatedAt Date N/A Read-only The date and time at which the resource was last updated (ISO 8601 format).
versionedAt Date N/A Read-only The date and time of the updatedAt property on the original resource. For deleted events, this will be the date and time the event was published.

Create Snapshot

Read Latest Snapshot

Read One Snapshot Version

Read All Snapshot Versions

Promotions

A promotion includes, at a minimum, source and target environment references, automatically generated source and target snapshots, the resource or resources to promote to the target environment, and a promotion plan for the promotion operation. You need to have the Environment Admin role for both the source and target environments. You can optionally include a specific source environment snapshot to use, as well as a mapping of the source environment configuration resource or resources to the target environment configuration resource or resources.

A PingOne admin having Environment Admin permissions can review the promotion plan, and update the promotion mapping and variable definitions or declarations as needed. The promotion plan is then regenerated based on the updates. Use the Read One Promotion or Read All Promotions to view the promotion plan.

If you do not set any promotion variables, the configuration resource or resources that you specify for the source or target environment will be used as is, and cannot be changed during the promotion operation. See Promotion Variables for more information.

When you choose to start the promotion operation, the promotion plan supplies the promotion operation instructions to the Promotions service. The Promotions service then:

  • Filters out any configuration resources that haven't changed, and calls the required target environment API using the new or altered resources.
  • Sets the promotion’s started_at and status values.
  • Collects any errors into a JSON array, and returns the errors.
  • Updates the promotion's completedAt and status values when the promotion operation is complete.

Promotions data model

Property Type Required? Mutable? Description
createdAt Date N/A Read-only The date and time the promotion was created.
completedAt Date N/A Read-only The date and time the promotion operation completed.
description String Optional Mutable A description of the promotion to be performed.
errors Object[] N/A Read-only An array of JSON objects correlating the configuration resource identifier in the source environment to the error messages from the target environment.
excludedResources Object[]* Optional Mutable An array of JSON objects. *Optionally, this can be an array of strings. Contains the resource identifiers, and resource URLs for the configuration resources to be excluded from promotion.
resourceMapping Map Optional Mutable A mapping of the configuration resource identifiers in the source environment to the configuration resource identifiers in the target environment.
promotionPlan Object[] N/A Read-only An array of JSON objects containing the promotion plan generated. The promotion plan is generated by the POST operation, but is returned only by either of the GET operations. For a DELETE operation, the payload property in the response will be empty.
promotionPlan.steps Object[] N/A Read-only An array of JSON objects identifying the resource or resources, the configuration of the resource or resources, and the target environment or environments.
promotionPlan.totalDistance Integer N/A Read-only (Internal use only.) A comparison metric the Configuration Management service uses to determine whether there is a comparable resource in the target environment to replace.
selectedResources Object[]* Optional Mutable An array of JSON objects. *Optionally, this can be an array of strings. Contains the resource identifiers, and resource URLs for the configuration resources selected for promotion. If this is omitted, the entire current environment is used (the environment ID is injected.)
sourceEnvironment String Optional Immutable A JSON object containing the ID of the source environment. If not specified, the current source environment for the actor is used.
sourceSnapshotId String Optional Mutable The identifier of the snapshot to use as the promotion source.
startedAt Date N/A Read-only The date and time the promotion operation started.
status String N/A Read-only An enumeration indicating the status of the promotion. This can be: NEW, PREPARING, READY, IN_PROGRESS, COMPLETED, VALIDATION_FAILED, or ERROR.
targetEnvironment Object Required Immutable A JSON object containing the identifier of the target environment.
targetSnapshotId String Optional Mutable The identifier of the snapshot to use as the promotion target.

Excluded Resources

Currently, not all resources, services, or products can be used in a promotion operation.

Excluded products or services
  • PingOne DaVinci (except for Forms)
  • PingOne Authorize
Excluded resources

Some resources can never be promoted, while others will be supported for promotion, but currently are not.

Permanently excluded resources

These resources are expected to never be supported for promotion:

  • Active Identity Counts
  • Activities
  • Adaptive Trust Policies
  • Applications Role Assignments
  • Application Signons
  • Application Signons Statistics
  • Certificates
  • Connectors
  • Dashboards
  • Data Exploration Batches
  • Data Explorations
  • Data Exploration Templates
  • Licenses
  • Licenses Expires At
  • Licenses Metrics Active Identity Counts
  • Licenses Name
  • PingOne for Enterprise Orchestrations
  • PingOne for Enterprise Callback
Currently excluded resources

These resources will be supported for promotion, but are not currently:

  • Admin Config
  • API Servers
  • Application Entitlements
  • Application Permissions
  • Application Resources
  • Application Roles
  • Applications Secret
  • Authorization Attributes
  • Authorization Changes
  • Authorization Conditions
  • Authorization Connector Templates
  • Authorization Policies
  • Authorization Processors
  • Authorization Rules
  • Authorization Services
  • Authorization Statements
  • Branding Settings
  • Connector Instances
  • Credential Counts
  • Credential Issuer Profile
  • Credential Types
  • Custom Domains
  • Davinci Applications
  • Decision Endpoints
  • Delegated Admins
  • Device Authentications
  • Digital Wallet Applications
  • External Services
  • Fido Devices Metadata
  • Flow Definitions
  • Flow Metadata
  • Flow Policies
  • Flows
  • Fraud Evaluations
  • Fraud Events Details
  • Fraud Feedbacks
  • Fraud Sessions
  • Identity Cloud
  • Identity Cloud Orchestrations
  • Images
  • Integrations
  • Languages
  • Legacy
  • Locales
  • Metrics
  • Migrate
  • Notification Callback
  • Notification Callback AWS email
  • Notification Callback Syniverse
  • Notification Callback Twilio
  • Notification Callback Whatsapp
  • Notifications
  • Notifications Quota
  • OAuth Jobs
  • OAuth Tokens
  • Organization Quota
  • Password Storage Scheme Config
  • Pingid
  • Pingid Mobile App Versions
  • Pingid Mobile Display Names
  • Pingid Mobile Os Versions
  • Portal
  • Presentation Sessions
  • Promotions
  • Promotion Variable Declarations
  • Propagation
  • Propagation Mappings
  • Propagation Plans
  • Propagation Provisioning Syncs
  • Propagation Revisions ID
  • Propagation Revisions ID Latest
  • Propagation Rules
  • Propagation Store Metadata
  • Propagation Stores
  • QS Dashboards
  • Rate Limit IP Configs
  • Recaptcha V2 Config
  • Resources Secret
  • Risk Evaluations
  • Risk Feedback
  • Roles
  • Seen Devices
  • Sessions
  • Snapshots
  • Software Licenses
  • Solutions
  • Subscriptions
  • Tiles
  • Total Identities
  • Translations
  • Users
  • Variables
  • Voice Phrases

Create Promotion

Start Promotion

Read All Promotions

Read One Promotion

Read Promotion Status

Update Promotion

Delete Promotion

Promotion Variables

Use promotion variables to to account for environment-specific differences, such as 3rd party integrations or URLs. You can specify configuration resource property values for either the source or target environment to be substituted for existing property values by the promotion operation. Only the promotion variables you set can change property values for use by the promotion operation. If you do not set any promotion variables, the configuration resource or resources that you specify for the source or target environment will be used as is, and cannot be changed during the promotion operation.

To use promotion variables, you need to:

  1. Specify the configuration resource to be promoted in a snapshot.
  2. Define the variable or variables to be used for a source or target environment configuration resource property. See Variable Definitions.
  3. Declare the variables to be used by the promotion operation. See Variable Declarations.

A few things to be aware of:

  • The variables are scoped only to the specified configuration resources, and are not applied to any dependent resources.
  • Variables are not versioned with a snapshot, so for each promotion operation, you need to ensure the variable settings for a configuration resource are correct.
  • Any configuration resources that you change directly without updating the variables will be overwritten by a subsequent promotion operation. This is because the promotion operation will use the existing variable set.

Variable Resources

Not all configuration resources or properties can be used as promotion variables. Here's the listing of configuration resources, and the associated properties that are supported as promotion variables:

Resource Properties
Applications acsUrls
audienceRestriction
corsSettings
defaultTargetUrl
deviceCustomVerificationUri
devicePathId
domainName
homePageUrl
idpSigning.algorithm
idpSigning.key.id
initiateLoginUri
jwks
jwksUrl
kerberos.key.id
mobile.bundleId
mobile.huaweiAppId
mobile.huaweiPackageName
mobile.integrityDetection.googlePlay.serviceAccountCredentials
mobile.packageName
mobile.uriPrefix
postLogoutRedirectUris
redirectUris
replyUrl
sloEndpoint
sloResponseEndpoint
spEncryption.certificate.id
spEntityId
spVerification.cert.id
subjectNameIdentifierFormat
targetLinkUri
Authentication relyingPartyId
Branding companyName
logo.href
Custom Domain domainName
Email Domains domainName
Gateways bindDN
bindPassword
kerberos.serviceAccountPassword
kerberos.serviceAccountUserPrincipalName
radiusClients.ip
Identity Providers appId
appSecret
authorizationEndpoint
clientEnvironment
clientId
clientSecret
clientSecretSigningKey
discoveryEndpoint
idpEntityId
issuer
jwksEndpoint
keyId
sloEndpoint
spSigning.key.id
ssoEndpoint
teamId
tenantId
tokenEndpoint
userInfoEndpoint
Notification Templates body
content
replyTo.address
replyTo.name
Notifications Phone Delivery Settings authToken
authentication.username
sid
Notifications key
type
Provisioning configuration.Administrator_Password
configuration.Administrator_Username
configuration.BASE_URL
configuration.BASIC_AUTH_PASSWORD
configuration.BASIC_AUTH_USER
configuration.CLIENT_ID
configuration.CLIENT_SECRET
configuration.ClientId
configuration.ClientSecret
configuration.GROUPS_RESOURCE
configuration.OAUTH_ACCESS_TOKEN
configuration.OAUTH_CLIENT_ID
configuration.OAUTH_CLIENT_SECRET
configuration.OAUTH_REFRESH_TOKEN
configuration.SALESFORCE_DOMAIN
configuration.SCIM_URL
configuration.ServiceNow_Url
configuration.TenantDomain
configuration.USERS_RESOURCE
configuration.password
configuration.tenantId
configuration.username
Trusted Email Addresses emailAddress

Variable Resources

Variable Definitions

When promoting a configuration, you need to define any variables you intend to use to substitute for existing property values. Once defined, you'll need to then declare a variable. See Variable Declarations for details.

Variable definitions data model

Property Type Required? Mutable? Description
createdAt Date N/A Read-only The date and time at which the resource was created (ISO 8601 format).
name String Required Mutable The name to use for the variable. This name must be unique in the environment.
updatedAt Date N/A Read-only The date and time at which the resource was last updated (ISO 8601 format).
value Object Required Mutable A JSON object containing the value to assign to the variable. Currently, the object type can be: String, List, or Integer.

Create Variable Definition

Read All Variable Definitions

Read One Variable Definition

Update Variable Definition

Delete Variable Definition

Variable Declarations

Before you can declare a variable (POST {{apiPath}}/environments/{{envID}}/promotionVariableDeclarations), you need to define the variable that you intend to use. See Variable Definitions for details.

Variable declarations data model

Property Type Required? Mutable? Description
createdAt Date N/A Read-only The date and time at which the resource was created (ISO 8601 format).
resourceId String Required Mutable The UUID of the configuration resource.
updatedAt Date N/A Read-only The date and time at which the resource was last updated (ISO 8601 format).
variables Map Required Mutable A mapping of configuration resource properties to the name values of defined variables. For example, for an applications resource, you might map the refreshTokenDuration property to a variable definition having a name value of refreshTokenDurationVar.

Create Variable Declaration

Read Variable Declarations

Update Variable Declaration

Update Variable Declaration

Delete Variable Declaration

Promotion Configuration

The promotionConfiguration endpoint sets and reads default target environment to be used for promotions. When you know that you'll be working with a specific target environment, you can set this environment as the default for the promotions you're doing.

Read Promotion Configuration

Update Promotion Configuration

PingOne Authorize Trust Framework

The PingOne Authorize trust framework service provides endpoints to define the entities and configurations to target policies and rules when making dynamic authorization requests.

The trust framework is based on attributes. These attributes have resolvers which bring contextual data values into the attribute. Resolvers can be conditional using an embedded condition or they can be a reference to a condition entity.

A service resolver references a service that can call out to a third-party HTTP service or the PingOne Protect service. Attributes can transform the value received from resolvers using embedded processors or referenced processors.

To create and manage the attributes, services, conditions, and processors, required by the PingOne Authorize trust framework, see:

Authorization Attributes

Authorization attributes provide contextual information that informs fine-grained dynamic authorization decisions. Attributes have the following characteristics:

  • An attribute has zero or more resolvers that bring the contextual data into the attribute value. The list of ordered resolvers are evaluated sequentially until a successful value is returned.

  • An attribute has zero or more processors that transform the data coming from the resolvers.

  • An attribute has a valueType property value that specifies the final output type of the attribute.

Authorization attributes data model

Property Type? Required? Mutable? Description
defaultValue String Optional Mutable The value to use if no resolvers are defined or if an error occurred with the resolvers or processors.
description String Optional Mutable The attribute resource's description.
fullName String Required Mutable A unique name generated by the system for each attribute resource. It is the concatenation of names in the attribute resource hierarchy.
id String N/A Read only The resource's unique identifier.
managedEntity Object Optional Read only A system-assigned set of restrictions and metadata related to the resource.
name String Required Mutable A user-friendly attribute name.
parent Object Optional Mutable The attribute resource's parent.
parent.id String Optional Mutable The attribute resource's parent ID.
processor Object Optional Mutable The attribute resource's processor.
processor.type String Optional Mutable The attribute resource's processor type. Options are JSON_PATH, SPEL, XPATH, COLLECTION_FILTER, COLLECTION_TRANSFORM, CHAIN, and REFERENCE. See Authorization processors processor type data model for additional properties for each processor type.
processor.name String Optional Mutable A user-friendly authorization processor name. The name value must be unique.
repetitionSource Object Optional Mutable A setting to designate the attribute as multi-valued and repeatable.
resolvers Array Optional Mutable The attribute resource's resolvers.
resolvers.type String Optional Mutable The attribute resource's resolver type. Options are REQUEST, CONSTANT, ATTRIBUTE, SERVICE, SYSTEM, CONFIGURATION, CURRENT_REPETITION_VALUE, CURRENT_USER_ID, and USER.
type String Required Read only The attribute type. Options are ATTRIBUTE.
valueType Object Required Mutable The value type object for the attribute.
valueType.type String Required Mutable The output type for the attribute. Options are BOOLEAN, STRING, NUMBER, XML, JSON, COLLECTION, DATE_TIME, LOCAL_TIME, LOCAL_DATE, LOCAL_DATE_TIME, ZONED_DATE_TIME, TIME_PERIOD, PERIOD, and DURATION.
version String Required Read only A random ID generated by the system for concurrency control purposes.

Authorization attributes resolvers type data model

Resolver type Description
REQUEST The value comes from the decision request.
ATTRIBUTE The value comes from another attribute. Additional properties are:
  • value, the value object.
  • value.id, the ID of the referring attribute.
CONSTANT The value provided is a constant. Additional properties are:
  • value, the constant value.
  • valueType, the output type of the constant. Options are BOOLEAN, STRING, NUMBER, XML, JSON, COLLECTION, DATE_TIME, LOCAL_TIME, LOCAL_DATE, LOCAL_DATE_TIME.
SERVICE The value comes from a service. Additional properties are:
  • value, the value object.
  • value.id, the ID of the referring service.
SYSTEM The value is provided by the system. Additional properties are:
  • value, a value that is set to either NULL or CURRENT_DATE_TIME.
CURRENT_REPETITION_VALUE The value of the repetition if the attribute belongs to a repetition scope.
CURRENT_USER_ID The value comes from the userContext property in the decision request.
USER The value is a PingOne user. Additional properties are:
  • query, a UserQuery object that provides a PingOne userId string.

Event types

The audit reporting events applicable to the authorize attribute service are:

Topic Event
authorize-model AUTHORIZE_ATTRIBUTE.CREATED
authorize-model AUTHORIZE_ATTRIBUTE.UPDATED
authorize-model AUTHORIZE_ATTRIBUTE.DELETED

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.

Create Authorization Attribute

Test Authorization Attribute

Read Authorization Attributes

Read One Authorization Attribute

Update Authorization Attribute

Delete Authorization Attribute

Authorization Services

Authorization services, also referred to as Policy Information Points or PIPs, represent third-party HTTP services or internal PingOne platform services (such as PingOne Protect) that may be called to retrieve data.

These endpoints provide operations to create, read, update, test, and delete authorization services.

Authorization services data model

Property Type? Required? Mutable? Description
cacheSettings Object Optional Mutable The service's cache settings.
cacheSettings.ttlSeconds integer Optional Mutable The service's time to live in seconds.
description String Optional Mutable The authorization service resource's description.
fullName String Required Mutable A unique name generated by the system for each service resource. It is the concatenation of names in the service resource hierarchy.
id String N/A Read only The resource's unique identifier.
name String Required Mutable A user-friendly service name.
parent Object Optional Mutable The service resource's parent.
parent.id String Optional Mutable The service resource's parent ID.
serviceType String Required Mutable The type of service. Options are NONE, HTTP, CONNECTOR. See the "serviceType property data model tables" section for information about the properties associated with each service type.
type String Required Read only The resource type. Options are SERVICE.
version String Required Read only A random ID generated by the system for concurrency control purposes.

The serviceType property supports the following three options: NONE, HTTP, and CONNECTOR. The NONE option does not require additional configuration. The HTTP and CONNECTOR service types require additional configuration property values in the request. The following tables describe the data models for these options.

HTTP serviceType data model properties
Property Type? Required? Mutable? Description
processor Object Optional Mutable The processor to transform the value returned from the resolver. Processor types are JSON_PATH, SPEL, XPATH, COLLECTION_FILTER, COLLECTION_TRANSFORM, CHAIN, and REFERENCE.
valueType Object Required Mutable The final output type of the service. Value types are BOOLEAN, STRING, NUMBER, XML, JSON, COLLECTION, DATE_TIME, LOCAL_TIME, LOCAL_DATE, LOCAL_DATE_TIME, ZONED_DATE_TIME, TIME_PERIOD, PERIOD, and DURATION.
serviceSettings Object Required Mutable The service settings object.
serviceSettings.maximumConcurrentReqests Integer Required Mutable The value must be greater than or equal to 1.
serviceSettings.maximumReqestsPerSecond Decimal Required Mutable The value must be greater than 0.
serviceSettings.timeoutMilliseconds Integer Required Mutable The value must be between 0 and 3000 (inclusive).
serviceSettings.type String Required Mutable The service type. Options are HTTP and CONNECTOR.

If the serviceSettings.type property is HTTP, the service supports the following service settings properties:

HTTP ServiceSettings property data model
Property Type? Required? Mutable? Description
type Object Required Immutable The type object.
url String Required Mutable The HTTP URL.
verb String Required Immutable The HTTP method. Options are GET, POST, PUT, DELETE, and HEAD.
body String Optional Mutable The HTTP request body.
contentType String Optional Mutable The HTTP request content type.
headers[] Array Optional Mutable The HTTP request headers. Each SPECIFIED HTTP header requires key and value properties. The value property input options are ATTRIBUTE or CONSTANT. If the value is an ATTRIBUTE, the input is expressed as a JSON object that specifies an attribute UUID. If the value is a CONSTANT, the input is a string.
authentication Object Required Mutable The authentication object. Authentication optinos are NONE, BASIC, TOKEN, and CLIENT_CREDENTIALS. For information about authentication type properties, see the data model table below.
tlsSettings Object Required Mutable The TLS object.
tlsSettings.tlsValidationType String Required Mutable The TLS validation type. Options are DEFAULT and NONE.
HTTP ServiceSettings authentication property data model

BASIC

Property Type? Required? Mutable? Description
name Object Required Mutable The user object.
name.id UUID Required Mutable The user name of the authenticator.
password Object Required Mutable The user object.
password.id UUID Required Mutable The password of the authenticator.

TOKEN

Property Type? Required? Mutable? Description
token Object Required Mutable The token object.
token.id UUID Required Mutable The token used to authenticate.

CLIENT_CREDENTIALS

Property Type? Required? Mutable? Description
tokenEndpoint String Required Mutable The token endpoint.
clientId String Required Mutable The client ID string.
clientSecret Object Required Mutable The client secret object.
clientSecret.id UUID Required Mutable The client secret string.
scope String Required Mutable The permissions that determine the resources that the application can access.
CONNECTOR data model properties
Property Type? Required? Mutable? Description
processor Object Optional Mutable The processor object, if specified.
valueType Object Required Mutable The value type object.
serviceSettings Object Required Mutable The service settings object for the CONNECTOR service type.
clientSecret.id UUID Required Mutable The client secret string.
scope String Required Mutable The permissions that determine the resources that the application can access.
CONNECTOR ServiceSettings property data model
Property Type? Required? Mutable? Description
type Object Required Immutable The type object.
channel Sting Required Mutable The channel value. Options are AUTHORIZE.
code String Required Mutable The code value. Options are P1_RISK.
capability String Required Mutable The capability associated with connector code and channel.
schemaVersion Integer Required Mutable The schema version in the connector template.
inputMappings[] Array Required Mutable The list of input mappings of matching the connector template.
inputMappings.type String Required Mutable The input mapping type. Options are ATTRIBUTE and INPUT. See the data model tables below for information about ATTRIBUTE and INPUT properties.
CONNECTOR inputMappings.type property data model

ATTRIBUTE

Property Type? Required? Mutable? Description
type Object Required Mutable The input mapping type.
value Object Required Mutable The input mapping value property.
value.id UUID Required Mutable An attribute ID.

INPUT

Property Type? Required? Mutable? Description
type Object Required Mutable The input mapping type.
value string Optional Mutable An input value.

Event types

The audit reporting events applicable to the authorization services service are:

Topic Event
authorize-model AUTHORIZE_SERVICE.CREATED
authorize-model AUTHORIZE_SERVICE.UPDATED
authorize-model AUTHORIZE_SERVICE.DELETED

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.

Create Authorization Service

Test Authorization Service

Read Authorization Services

Read One Authorization Service

Update Authorization Service

Delete Authorization Service

Authorization Conditions

Conditions in PingOne Authorize define authorization logic by comparing one thing to another. Conditions evaluate to either true or false. The authorization conditions service provides endpoints to create, read, update, test, and delete trust framework authorization conditions.

Authorization conditions data model

Property Type? Required? Mutable? Description
condition Object Required Mutable The authorization condition object.
condition.type String Required Mutable The authorization condition type. Options are COMPARISON, AND, OR, EMPTY, NOT, REFERENCE.
condition.conditions[] Object Required Mutable A set of conditions.
condition.conditions.type String Required Mutable The type of condition.
condition.conditions.comparator String Required Mutable The operator used to evaluate the condition.
condition.conditions.left Object Required Mutable An object that defines the left side of the condition statement.
condition.conditions.right Object Required Mutable An object that defines the right side of the condition statement.
description String Optional Mutable The authorization condition resource's description.
fullName String Required Mutable A unique name generated by the system for each authorization condition resource. It is the concatenation of names in the condition resource hierarchy.
id String N/A Read only The resource's unique identifier.
name String Required Mutable A user-friendly authorization condition name.
parent Object Optional Mutable The authorization condition resource's parent.
parent.id String Optional Mutable The authorization condition resource's parent ID.
type String Optional Mutable The condition resource's type. Options are CONDITION.
version String Required Read only A random ID generated by the system for concurrency control purposes.

Authorization conditions condition type data model

Condition type Description
AND The and logical condition. Additional properties are:
  • conditions, the list of conditions that must be met.
OR The or logical condition. Additional properties are:
  • conditions, the list of conditions of which one must be met.
NOT The not logical condition. Additional properties are:
  • condition, the list of conditions.
EMPTY The empty condition, which specifies no conditions to be met.
REFERENCE The reference condition. Additional properties are:
  • reference, the reference object.
  • reference.id, the ID of an authorization condition.
COMPARISON The comparison condition. Additional properties are:
  • left, the value on the left side of the comparison operator.
  • right, the value on the right side of the comparison operator.
  • comparator, the comparison operator. Options are IS_MEMBER_OF, IS_NOT_MEMBER_OF, CONTAINS_GROUP, DOES_NOT_CONTAIN_GROUP, CONTAINS, NOT_CONTAINS, EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESSER_THAN, LESSER_THAN_OR_EQUAL, REGULAR_EXPRESSION, STARTS_WITH, NOT_STARTS_WITH, ENDS_WITH, NOT_ENDS_WITH, MATCHES, NOT_MATCHES, IS_IN, IS_NOT_IN, IN_CIDR_BLOCK, NOT_IN_CIDR_BLOCK

Event types

The audit reporting events applicable to the authorization condition service are:

Topic Event
authorize-model AUTHORIZE_CONDITION.CREATED
authorize-model AUTHORIZE_CONDITION.UPDATED
authorize-model AUTHORIZE_CONDITION.DELETED

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.

Create Authorization Condition

Test Authorization Condition

Read Authorization Conditions

Read One Authorization Condition

Update Authorization Condition

Delete Authorization Condition

Authorization Processors

Authorization processors transform the data coming from the resolvers. Processors manipulate and transform data, including extracting details from structured data, or converting data to different formats. These endpoints provide operations to create, read, update, and delete authorizaton processor resources.

Authorization processors data model

Property Type? Required? Mutable? Description
description String Optional Mutable The authorization processor resource's description.
fullName String Required Mutable A unique name generated by the system for each authorization processor resource. It is the concatenation of names in the processor resource hierarchy.
id String N/A Read only The resource's unique identifier.
name String Required Mutable A user-friendly authorization processor name.
parent Object Optional Mutable The authorization processor resource's parent.
parent.id String Optional Mutable The authorization processor resource's parent ID.
processor Object Optional Mutable The authorization processor resource's processor object.
processor.type String Optional Mutable The authorization processor resource's processor type. Options are JSON_PATH, SPEL, XPATH, COLLECTION_FILTER, COLLECTION_TRANSFORM, CHAIN, REFERENCE. See Authorization processors processor type data model for additional properties for each processor type.
processor.name String Optional Mutable A user-friendly authorization processor name. The name value must be unique.
type String Optional Mutable The processor resource's processor type. Options are PROCESSOR.
version String Required Read only A random ID generated by the system for concurrency control purposes.

Authorization processors processor type data model

Processor type Description
JSON_PATH The JSON path expression processor. Additional properties are:
  • expression, the JSON path expression.
  • valueType, the output type for the value. Options are BOOLEAN, STRING, NUMBER, XML, JSON, COLLECTION, DATE_TIME, LOCAL_TIME, LOCAL_DATE, LOCAL_DATE_TIME.
CHAIN The CHAIN processor. Additional properties are:
  • processors, the list of processors to apply in the given order.
COLLECTION_FILTER The collection filter processor. Additional properties are:
  • predicate, the XPath expression.
COLLECTION_TRANSFORM The collection transform processor. Additional properties are:
  • processors, the list of processors to apply in the given order.
REFERENCE The reference processor. Additional properties are:
  • processor, the processor object.
  • processor.id, the ID of an authorization processor.
SPEL The SpEL expression processor. Additional properties are:
  • expression, the SpEL expression.
  • valueType, the output type for the value. Options are BOOLEAN, STRING, NUMBER, XML, JSON, COLLECTION, DATE_TIME, LOCAL_TIME, LOCAL_DATE, LOCAL_DATE_TIME.
XPATH The XPath expression processor. Additional properties are:
  • expression, the XPath expression.
  • valueType, the output type for the value. Options are BOOLEAN, STRING, NUMBER, XML, JSON, COLLECTION, DATE_TIME, LOCAL_TIME, LOCAL_DATE, LOCAL_DATE_TIME.

Event types

The audit reporting events applicable to the authorize processors service are:

Topic Event
authorize-model AUTHORIZE_PROCESSOR.CREATED
authorize-model AUTHORIZE_PROCESSOR.UPDATED
authorize-model AUTHORIZE_PROCESSOR.DELETED

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.

Create Authorization Processor

Read Authorization Processors

Read One Authorization Processor

Update Authorization Processor

Delete Authorization Processor

Authorization Connector Templates

This endpoint provides an operation to view the authorization connector templates associated with the specified environment.

Connector templates data model

Property Type? Required? Mutable? Description
type String Required Immutable The type of connector template.
channel String Required Mutable The connector template channel.
code String Required Mutable The code associated with the service.
capability String Required Mutable The capability associated with the connector code and channel.
schemaVersion Integer Required Mutable The schema version of the connector template.
inputMappings Array Required mutable The list of input mappings of the connector template.
inputMappings.type String Required mutable The type of input mapping. Options are ATTRIBUTE, INPUT.
inputMappings.property string Required mutable The property associated with the input mapping.
cacheSettings Object Optional Mutable An object that specifies the cache settings.
cacheSettings.ttlSeconds Integer Optional Mutable The time to live setting specified in seconds.

Response codes

Code Message
200 Successful operation.
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.

Read Authorization Connector Templates

PingOne Authorize Editor Policy Management

PingOne Authorize policies model business requirements into authorization logic using elements created in the PingOne Authorize Trust Framework.

Policies are based on application requirements and the regulations that you’re complying with. Your organization imposes many conditions and constraints on access control. Policies capture these constraints in rules that define the circumstances under which users can access certain resources.

The policy management endpoints include:

Authorization Policies

Authorization policies specify the statements (directives that instruct the policy decision service to perform additional processing in conjunction with an authorization decision), conditions (authorization logic comparing one thing to another), and combining algorithms (the process for combining multiple rules) to determine an authorization decision.

Authorization policies data model

Property Type? Required? Mutable? Description
children Array Optional Mutable The list of child policies or rules. Can be either referenced or embedded.
combiningAlgorithm Object Required Immutable The algorithm that determines how rules are combined to produce an authorization decision. For details, see Authorization Rules.
condition Object Optional Mutable The authorization condition object. For details, see Authorization Conditions.
description String Optional Mutable The authorization policy resource's description.
enabled Boolean Optional Mutable The setting that determines whether the decision node is evaluated. The default value is true.
id String N/A Read only The policy resource's unique identifier.
name String Required Mutable A user-friendly policy name. The name value must be unique.
repetitionSettings Object Optional Mutable Applies the policy to each item of the specific attribute, filtered by decision.
repetitionSettings.source Object Optional Mutable The source associated with this rule.
repetitionSettings.source.id String Optional Mutable The UUID of the repetition source associated with this rule.
repetitionSettings.decision String Optional Mutable The decision filter. Options are PERMIT, DENY, NOT_APPLICABLE, and INDETERMINATE.
statements Object Optional Mutable The authorization statements object. Can be either referenced or embedded. For details, see Authorization Statements.
type String Required Mutable The attribute type. Options are POLICY.
version String Required Read only A random ID generated by the system for concurrency control purposes.

Authorization embedded policies data model

Property Type? Required? Mutable? Description
type String Required Mutable The embedded policy type. Options are POLICY.
value.id String Required Immutable The embedded policy ID.
name String Required Mutable The embedded policy name.
description String Optional Mutable The embedded policy description.
enabled Boolean Optional Mutable Specifies whether the embedded policy is enabled.
statements Object Optional Mutable The statements associated with this embedded policy.
conditions Object Optional Mutable The conditions associated with this embedded policy.
combiningAlgorithm Object Required Mutable The combining algorithm for the embedded policy.
children Array Optional Mutable The list of sub-child policies or rules associated with the embedded policy.
repetitionSettings Object Optional Mutable The repitition settings associated with the embedded policy.

Authorization policies embedded rules data model

Property Type? Required? Mutable? Description
type String Required Mutable The embedded rule type. Options are RULE.
value.id String Required Immutable The embedded rule ID.
name String Optional Mutable The embedded rule name.
description String Optional Mutable The child policy description.
enabled Boolean Optional Mutable Specifies whether the child policy is enabled.
statements Object Optional Mutable The statements associated with this child policy.
conditions Object Optional Mutable The conditions associated with this child policy.
effectSettings Object Required Immutable The settings that determine how the children are combined to produce an outcome for the policy.

Event types

The audit reporting events applicable to the authorize policies service are:

Topic Event
authorize-model AUTHORIZE_POLICIES.CREATED
authorize-model AUTHORIZE_POLICIES.UPDATED
authorize-model AUTHORIZE_POLICIES.DELETED

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.

Create Authorization Policy

Test Authorization Policy

Read Authorization Policies

Read One Authorization Policy

Update Authorization Policy

Delete Authorization Policy

Authorization Statements

Statements instruct the policy decision service to perform additional processing in conjunction with an authorization decision. In addition to allowing or blocking access to a resource, using statements, the decision service can attach information to decision responses and filter and transform API payloads.

Authorization statements data model

Property Type? Required? Mutable? Description
appliesif String Required Mutable Specifies when to attach to a final decision. Options are ANYTHING, FINAL_DECISION_MATCHES, and PATCH_MATCHES.
appliesTo String Required Mutable Specifies what result the statement applies to. Options are ANYTHING, PERMIT, DENY, PERMIT_OR_DENY, and INDETERMINATE.
attributes Object Required Mutable The attributes attached to the statement.
code String Required Mutable The statement code.
description String Optional Mutable The authorization processor resource's description.
value.id String N/A Read only The resource's unique identifier.
name String Required Mutable A user-friendly authorization processor name. The name value must be unique.
obligatory Boolean Optional Mutable Specifies that the statement must be fulfilled as a condition of authorizing the decision request. The defaule is false.
payload String Required Mutable The statement payload.
services Object Required Mutable The services attached to the statement.
version String Required Read only A random ID generated by the system for concurrency control purposes.

Event types

The audit reporting events applicable to the authorize statements service are:

Topic Event
authorize-model AUTHORIZE_STATEMENT.CREATED
authorize-model AUTHORIZE_STATEMENT.UPDATED
authorize-model AUTHORIZE_STATEMENT.DELETED

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.

Create Authorization Statement

Read Authorization Statements

Read One Authorization Statement

Update Authorization Statement

Delete Authorization Statement

Authorization Rules

Rules in PingOne Authorize identify the statements and conditions by which a decision node is evaluated. If the condition is true, the decision node is evaluated. Otherwise, it is not. PingOne Authorize policies can combine multiple rules to produce a Permit, Deny, Indeterminate, or Not Applicable decision.

Authorization rules data model

Property Type? Required? Mutable? Description
condition Object Optional Mutable The authorization condition object. For details, see Authorization Conditions.
description String Optional Mutable The authorization rule resource's description.
effectSettings Object Required Immutable An object that determines how the children are combined to produce an outcome for the policy.
enabled Boolean Optional Mutable The setting that determines whether the decision node is evaluated. The default value is true.
id UUID Required Read only The resource's unique identifier.
name String Required Mutable A user-friendly authorization rule name. The name value must be unique.
statements Object Optional Mutable The authorization statements object. For details, see Authorization Statements.
type String Required Immutable The condition resource's type. Options are CONDITION.
version UUID Required Read only A random ID generated by the system for concurrency control purposes.

Event types

The audit reporting events applicable to the authorization rules service are:

Topic Event
authorize-model AUTHORIZE_RULES.CREATED
authorize-model AUTHORIZE_RULES.UPDATED
authorize-model AUTHORIZE_RULES.DELETED

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.

Create Authorization Rule

Test Authorization Rule

Read Authorization Rules

Read One Authorization Rule

Update Authorization Rule

Delete Authorization Rule

Changelog

The following changes have been made to the PingOne APIs or the associated SDKs.

Release Date Description
May 11, 2025 The use of OATH tokens as an authentication method, which was introduced a number of months ago for environments where PingID accounts were integrated, is now available for all PingOne environments that include the PingOne MFA or PingID services. You can use the oathTokens endpoint to add OATH tokens to the environment and carry out actions such as revoking or resyncing tokens. For For details, see OATH tokens and the Create MFA User Device (OATH token) example.
Apr 30, 2025 You can now soft-delete PingOne PRODUCTION environments, making the environment non-operational for a waiting period before it can be deleted. This is to help protect you from inadvertently deleting a Production environment. See Environments and Deleting Environments for more information.
Apr 30, 2025 The TEXTBLOB form field type (fieldTypes property) has been deprecated. See Forms for more information.
Apr 29, 2025 We've published a new Getting Started guide for the PingOne Platform APIs, and removed the existing Tutorial guide (the Getting Started guide now covers this information). See PingOne for Developers Getting Started.
Apr 28, 2025 In your notification policies, you can now define waiting periods before users can request another notification such as another OTP, as well as a maximum number of such requests before the user is temporarily locked out. See the new cooldownConfiguration object in Notification Policies and the Create Notification Policy / Environment example.
Apr 28, 2025 Your MFA policies can now include WhatsApp as an authentication method. For details, see Instant Messaging Delivery Settings, the Offline device (SMS, voice, email, WhatsApp) authentication policy data model in Device Authentication Policies, and the Create WhatsApp Content example.
Apr 22, 2025 The platform now supports the x5t signature header in the signed JWT. See Applications OIDC settings data model.
Apr 22, 2025 The platform now supports configuration options for Davinci flow execution using the PingOne authorize endpoint in which the response returns JSON. See DaVinci Flow Executions.
Apr 21, 2025 The platform now supports DaVinci Admin API operations through the PingOne API resource server to manage DaVinci workflow configuration. See DaVinci Admin APIs for links to all available services.
Apr 7, 2025 We've added Early Access Features APIs enabling you to adopt and provide feedback on PingOne features before the General Availability release. See Early Access Features for more information.
Apr 2, 2025 You can now specify that a mobile push requires the user to match a number that they were shown when requesting access. To enable the option for an application, use the new push.numberMatching.enabled property in your MFA policy. See Device Authentication Policies. To control how the user performs the matching - selection from a group of three numbers or manually entering the number - use the push.numberMatching.type property when configuring the mobile settings for the application. See Application Operations.
Apr 2, 2025 You can now cancel an authentication process that has already begun. This can be used in situations where a user decides they want to use a different authentication device. For details, see the Cancel Device Authentication and Cancel Authentication Flow examples.
Mar 25, 2025 When using the devices endpoint to request details of a single MFA device or all MFA devices, responses for activated FIDO2 devices can now include the AAGUID for the type of authenticator. For details, see the new fidoDeviceMetadata object in MFA devices.
Mar 18, 2025 When configuring an MFA policy, you can now specify for FIDO2 devices the maximum number of times authentication can fail before the user is blocked temporarily, and how long the user should be blocked. See the new fido2.failure object in Device Authentication Policies.
Mar 10, 2025 ID tokens now include a new claim called p1.mfa_device_id, the ID of the device that was used to authenticate. See ID Token claims.
Mar 4, 2025 For workforce contexts, risk evaluations can now include the new PingID Device Trust predictor. For details, see Risk Predictors and the Create Risk Evaluation (includes device trust predictor) example.
Feb 25, 2025 When determining the language to use for a notification, PingOne now also takes into consideration the Accept-Language header in the request. For details, see Runtime logic for content selection in Notifications Templates.
Feb 25, 2025 When creating or updating an MFA policy, you can now specify the notification policy that should be used with the MFA policy by using the new notificationsPolicy.id field. See Device Authentication Policies and the Create Device Authentication Policy example.
Feb 24, 2025 In MFA policies, you can now include a "remember me" option so that users do not have to authenticate when accessing applications from a device they have used before. See the new rememberMe object in Device Authentication Policies and the implementation instructions in Remembered Devices.
Feb 18, 2025 When creating or updating a population, if you do not specify a theme.id value in your request, the default theme for the current environment is used. See Create Population and Update Population.
Feb 12, 2025 The platform supports token fulfillment in PingOne, enabling admins to map attributes from a source's authentication JWT to the PingOne generated token to improve interoperability with OIDC applications. See Use an authentication JWT for token fulfillment.
Feb 5, 2025 You can now define multiple custom providers to use for SMS / voice notifications. In environments with more than one custom provider, you can specify in your notification policies the order of provider preference to use in different geographical locations. For details, see the new providerConfiguration object in Notification Policies.
Jan 28, 2025 We've added the ability for an OIDC application to request to terminate a user session from the IdP associated with the user using only the ID token. See GET IdP Signoff for details.
Jan 21, 2025 The platform now supports the LINKEDIN_OIDC identity provider type to specify LinkedIn as an external identity provider. The LINKEDIN type is deprecated and will be removed from the platform in February, 2026. For details, see Create Identity Provider (LinkedIn OIDC).
Jan 13, 2025 PingOne Verify added an additional provider, Babel Street Rosette, to enhance matching of biographic data on submitted documents to corresponding data on verified records. A new request, Verify Identity Record Matching provides access to this provider outside the context of a verify transaction. This new request requires a specific license entitlement.
Jan 9, 2025 You can now define a period during which a specific user should be allowed to bypass MFA. See Allow MFA Bypass for User.
Jan 9, 2025 For RADIUS gateways, support has been added for the EAP-MSCHAP v2 protocol. Also, to help block Blast RADIUS attacks, a new object called blastRadiusMitigation has been added. See Gateway Management.
Jan 9, 2025 When defining FIDO policies, you can now include the new publicKeyCredentialHints array to provide public key credential hints to the browser in order to give priority to the authentication method that the user is most likely to use. For details, see FIDO Policies.
Jan 7, 2025 For PingOne environments where PingID accounts have been integrated, you can use the new oathTokens endpoint to add OATH tokens to the environment and carry out actions such as revoking or resyncing tokens. For details, see OATH tokens and the Create MFA User Device (OATH token) example.
Dec 18, 2024 The platform now supports DaVinci runtime endpoints for use with the DaVinci SDK. For details, see DaVinci Flow Executions.
Dec 9, 2024 When defining FIDO policies, you can now use the new userPresenceTimeout object to specify the amount of time the user has to perform a user presence gesture with their FIDO device before the request expires. For details, see FIDO Policies.
Nov 5, 2024 You can now return a refresh token by setting offline_access as a scope on the application's resource grant and including offline_access in the scope parameter of the authorize request. See Authorization for details.
Oct 29, 2024 We've added the SAML property sessionNotOnOrAfterDuration to allow you to specify a custom duration for the lifetime of a SAML assertion. See SAML data model for details.
Oct 16, 2024 You can specify a replacement background of a uniform color to apply to user self portraits with the Update Verified Data Portrait Background request.
Oct 15, 2024 The platform now supports custom admin roles. For details, see Roles Management.
Oct 9, 2024 You can now use the emailDeliverySettings endpoint to configure the sending of notifications via an external email service. For details, see Email Delivery Settings.
Oct 7, 2024 For SMS, voice, and email authentication, you can now customize the length of the OTP that is shown to users. For details, see the new otpLength parameter in the Offline device (SMS, voice, email) authentication policy data model under Device Authentication Policies.
Sep 30, 2024 To help users recognize which application the OTP displayed in their authenticator app is for, your MFA policies can now specify text that should be displayed alongside the OTP. For details, see the new uriParameters object in the TOTP device authentication policy data model under Device Authentication Policies.
Sep 20, 2024 We've added the ability to modify Administrator Security to support enhanced admin security. Enhanced security requires the use of PingOne MFA for all admin sign-ons to PingOne. See Administrator Security for more information.
Aug 29, 2024 When retrieving verified data with Read All User Verified Data, you can use the attempt query parameter to limit the number of retries returned and thus reduce the size of the response.
Aug 19, 2024 PingOne Protect now has a risk predictor called Traffic Anomaly intended to detect traffic anomalies in terms of variables such as users, devices, and sessions. The Traffic Anomaly predictor will eventually include a variety of rules, some of which you can select to enable or disable. Currently, the predictor detects situations where there are a large number of risk evaluations requested for a single user within a short period of time, and optionally can also detect situations where the number of users per device during a given period is suspicious. When a risk level of High is calculated for a Traffic Anomaly predictor, the recommendedAction field in the risk evaluation response has the value DENY, indicating that you should probably deny access. To create a Traffic Anomaly predictor, set the type parameter to the new value TRAFFIC_ANOMALY. If you want to also check the number of users per device, use the objects described in the traffic anomaly risk predictor data model. For details, see Risk Predictors and Risk evaluations.
Aug 5, 2024 When creating composite predictors, you can now include conditions that check what PingOne user groups the user belongs to. For details, see the Composite Risk Predictors section in Risk Predictors and the relevant example.
Aug 5, 2024 The Bot Detection predictor now has an option that you can enable to expand the range of bot activity that PingOne Protect can detect. For details, see the new field includeRepeatedEventsWithoutSdk under Risk Predictors.
Jul 22, 2024 For MFA, there is now an option to use dynamic linking to attach a unique identifier to the registration of a FIDO device. For details, see MFA devices.
Jul 15, 2024 MFA is now enforced for environment administrators during registration. You can read and update admin sign-on settings using the new Administrator Security endpoints. For details, see Administrator Security.
Jul 3, 2024 The Suspicious Device predictor now includes an option to specify that any risk policies that include the predictor will require that the Signals SDK payload be provided as a signed JWT whose signature will be verified before proceeding with risk evaluation. For details, see Risk Predictors.
Jun 27, 2024 We've added the new role "Application Owner", enabling you to restrict administrator access to specific applications. Use this role to assign application developers permissions only to the applications they manage. For details, see Roles.
Jun 18, 2024 When creating risk evaluations, you can now provide additional detail about the context of the flow by providing a value for flow.subtype in addition to flow.type. For details, see Risk evaluations.
Jun 17, 2024 A new endpoint, riskFeedback, has been added to allow you to provide feedback on the accuracy of specific risk evaluations that were carried out. Each such call can include feedback for up to 100 risk evaluations, and for each you can specify a feedback category and a reason for including the evaluation in that category, For details, see Providing feedback for risk evaluations.
Jun 4, 2024 For MFA, there is now an option to use dynamic linking to attach a unique identifier to a FIDO transaction. For details, see Create a request property JWT and Device authentications data model.
Jun 3, 2024 When creating or updating MFA policies, you can now include a field called promptForNicknameOnPairing to allow users to provide nicknames for devices during pairing. For details, see Device Authentication Policies.
May 28, 2024 The Forms service now supports a social login button as a field type option. For details, see Forms.
May 6, 2024 The platform now supports the AU (Australia/Asia Pacific) region. The platform continues to support the AP (Asia Pacific) region. However, if your environments use the AP region designation (api.pingone.asia domain) for Asia-Pacific countries, be aware that this region does not support the migration of PingID customers (or the PingID product) to the PingOne platform. To get PingID platform support for your Asia-Pacific environments, use the AU region designation (api.pingone.com.au domain) when creating your new environments. For details, see Working with PingOne APIs.
Apr 24, 2024 The Resources service now provides a property to add application permissions to access tokens. For details, see Resources.
Apr 8, 2024 Simplify changing your PingOne regional domain with an environment variable, tld, in the public PingOne environment template that represents the top level domain (TLD) for your PingOne domain, such as com or eu. All the {{...Path}} variables, such as {{apiPath}} and {{authPath}}, reference {{tld}}. To change your region's top level domain, merely change the value of {{tld}}. See PingOne API domains for more information.
Apr 4, 2024 With Managed Credential Issuance, client applications can issue and update credentials using Create Credential Type (managed) rather than an Issuance Rule.
Apr 3, 2024 You can submit a redirect URL and redirect message, used and seen by users when submitting verification documents, in the body of Create Verify Transaction.
Apr 3, 2024 You can issue and update user credentials via a Create a User Credential or Update a User Credential call rather than an Issuance Rule.
Apr 3, 2024 When you create a trusted email domain, PingOne now prepares an additional text record that reflects the association of the domain with the specific PingOne environment. If you add this new record to your DNS, any "sender" email address belonging to the domain is set to active status as soon as you create it, with no need for a verification email. For details, see Trusted Email Domains.
Apr 2, 2024 FIDO policies now include an option called aggregateDevices that you can use to specify that the displayed list of available authentication methods should include only a single generic entry for FIDO2 devices, even if the user has multiple paired FIDO2 devices. For details, see FIDO Policies. With the introduction of this feature, responses to requests that use the deviceAuthentications and flows endpoints may now include a field called aggregateFido2Devices, indicating whether the available authentication method list should include only a single generic FIDO2 option.
Mar 12, 2024 We've added the new LDAP Gateway attribute userTypes.updateUserOnSuccessfulAuthentication. When enabled, on user sign on, user attributes are updated based on responses from the LDAP server. For details, see Gateway LDAP data model.
Mar 4, 2024 The external IdP service now supports PKCE. A new pkceMethod property has been added to the base IdP data model. For details, see Identity Provider Management.
Mar 4, 2024 PingOne Protect now has a new risk predictor called Email Reputation to detect the use of disposable email addresses during registration. The value of the type parameter for this predictor is EMAIL_REPUTATION. For details, see Risk Predictors. For risk evaluations based on policies that include an email reputation predictor, the response may include a value of TEMP_EMAIL_MITIGATION for the result.recommendedAction field. For details, see Risk evaluations.
Mar 4, 2024 For risk evaluations that use a risk policy with the New Device predictor, the response now includes the field details.device.lastSeen, which represents the date and time that the device was last seen. If an externally-maintained device ID was provided in the risk evaluation request, the response will include externalLastSeen for the date and time that the device was last seen. For details, see Risk evaluations.
Feb 28, 2024 For situations where a user did not receive the one-time passcode (OTP) that was sent for pairing a device, you can now use the devices endpoint to resend the OTP. For details, see Resend Pairing Code.
Feb 21, 2024 The platform now supports the device_code device authorization grant type on an application configuration, and it also provides endpoints to initiate and manage a device authorization flow. For details, see Device Authorization Grant.
Feb 20, 2024 A new field, fidoUserVerification, was added to the information that can be included in MFA device reports generated with the dataExplorations endpoint. For details, see Reporting.
Feb 14, 2024 PingOne now supports the CLIENT_SECRET_JWT and PRIVATE_KEY_JWT token endpoint authentication methods for OIDC applications. For details, see the jwks and jwksUrl properties in Application Operations, the client_assertion and client_assertion_type properties in OpenID Connect/OAuth 2, Token (authorization_code) (CLIENT_SECRET_JWT), Token (authorization_code) (PRIVATE_KEY_JWT), and Configure CLIENT_SECRET_JWT as the Token Auth Method.
Feb 12, 2024 PingOne Protect now has a new risk predictor to prevent Adversary-in-the-Middle (AitM) attacks. To create an AitM predictor, set the type parameter to the new value ADVERSARY_IN_THE_MIDDLE and use the whiteList parameter to specify the legitimate domains that your users will access for your restricted resources. For details, see Risk Predictors.
Feb 5, 2024 PingOne Verify no longer reads or uses verifyStatus on the user. The PingOne Neo Verify Verify Status endpoint, /environments/{{envID}}/users/{{userID}}/verifyStatus and its two operations, Read User Verification Status and Update User Verification Status at the same URL, are deprecated. The endpoint and requests will be removed February 2025.
Jan 19, 2024 We've added the icon property to the Environments service, enabling you to assign an icon to a PingOne environment. See the Environments data model for details.
Jan 16, 2024 The platform's client secret configuration now supports optional parameters to designate the replaced secret as a "previous" secret that remains valid for a specified period, up to 30 days. For details, see Update Application Secret and Create Resource Client Secret.
Jan 11, 2024 The platform supports the PingOne Authorize application resources and roles services, which provide endpoints to define custom resources, roles, and permissions to protect external application resources. For details, see PingOne Authorize Application Resources and Roles.
Jan 8, 2024 The platform supports reduced self-service scopes when the mfa authentication method is not included as an amr claim value in the token. For details, see PingOne self-management scopes.
Jan 7, 2024 Changes have been made to the steps required to retrieve MFA device reports generated as files. This is reflected in the responses to the relevant requests. For details, see Reporting. Note that the .zip file containing the report is now password-protected and cannot be opened without the password that is returned.
Jan 4, 2024 A field called device.externalId has been added to the Event data model for risk evaluations. You can use this field to send an externally-maintained device ID to the risk evaluation. If you provide such an ID, that is the device ID that will be used rather than the device ID provided by the Signals SDK. For details, see Risk evaluations.
Jan 3, 2024 We've added a corsSettings object to support applications using cross-origin resource sharing (CORS). See Cross-origin resource sharing, and the corsSettings properties in the Applications data models for OIDC, SAML, and WS-Federation.
Dec 15, 2023 You can now set and get the default identity provider (IdP) for a population. See Update Population Default IdP and Read One Population Default IdP for details.
Dec 8, 2023 PingOne Platform API collections in the PingOne public workspace now use Postman Collection-Level Authorization of type bearer. All requests that use bearer token authorization are now set to Inherit authorization from parent.
Dec 4, 2023 The PingOne Neo Verify User Data endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/userData and its only operation, Read User Verification Data at the same URL, are deprecated. The endpoint and request will be removed December 2024.
Dec 4, 2023 The New Device Paired notification template now has an optional variable called report.fraud. If you include this variable, the notification will include a link for reporting fraudulent pairing attempts. For details, see Notifications Templates.
Nov 16, 2023 We've added documentation for the supported password encoding schemes. See Password encoding for more information.
Oct 24, 2023 You can now assign admin roles to user groups. See Group Role Assignments.
Oct 12, 2023 PingOne now supports outbound mutual TLS (mTLS) authentication with webhooks. You can upload a key with a usageType of OUTBOUND_MTLS and pass the ID to the tlsClientAuthKeyPair.id property when creating or updating a webhook. For more information, see Subscriptions (webhooks).
Oct 4, 2023 Added the displayName, sourceId, and sourceType parameters to allow querying of external user groups. See Groups.
Sep 19, 2023 When creating composite predictors, it is now possible to create additional sets of conditions to form an if / else if structure. To facilitate this, the composition object has been replaced with an array called compositions. To ensure backward compatibility, requests that contain the single composition object are still supported. For details, see Risk Predictors.
Sep 18, 2023 When providing the flow type as input for a risk evaluation, you can now use other types in addition to AUTHENTICATION. The new flow types supported are: REGISTRATION, ACCESS, AUTHORIZATION, and TRANSACTION. See Risk Evaluations.
Sep 18, 2023 In the MFA Settings for an environment, you can now specify whether MFA should be enabled by default for a user when their account is created. For details, see users.mfaEnabled in MFA settings.
Sep 14, 2023 If you create a pairing key that is shared by multiple applications, but define different pairing key lifetimes for the different applications, all the applications using the pairing key now use the most strict setting that you specified for key lifetime (shortest time).
Sep 7, 2023 We've added a Correlation-Id setting in the header of Phone Delivery Settings requests to the custom provider enabling you to track notifications sent by the custom provider using the Correlation-Id value. See Phone Delivery Settings.
Sep 5, 2023 We've added information regarding how to handle client secret updates for external identity providers. See Update Identity Provider.
Sep 5, 2023 You can now specify Elliptical Curve Digital Signature Algorithm (ECDSA) signing certificate algorithms for your SAML identity providers and applications. See Create Identity Provider (SAML) and SAML Application Settings Data Model.
Aug 10, 2023 You can now use the RequestedAuthnContext parameter to specify lower-priority application flow policies for SAML applications. See Application Flow Policy Assignments.
Jul 31, 2023 Added a new endpoint to PingOne Authorize to manage API service deployment. See API Service Deployment.
Jul 26, 2023 We've added the new roles DaVinci Admin and DaVinci Read-Only Admin. Currently, you cannot assign these roles to a Worker app. For details, see Roles.
Jul 5, 2023 A new field called newDeviceNotification has been added for MFA policies to allow you to specify that users should receive an SMS or email notification when a new device is added to their account. For details, see Device Authentication Policies.
Jul 5, 2023 New fields were added to the information that can be included in MFA device reports generated with the dataExplorations endpoint: deviceIntegrityStateCompromised, deviceIntegrityStateReason, deviceIntegrityStateTimestamp, deviceIntegrityStateAdvice, extension, fidoBackupEligibility, fidoBackupState, lastDeviceTrxTime. For details, see Reporting.
Jun 30, 2023 Two new risk predictors - Bot Detection and Suspicious Device - have been added. For details, see Risk Predictors and Risk Evaluations.
Jun 30, 2023 For including data from the Signals SDK in risk evaluations, the data in now sent using the sdk.signals.data property rather than sending the data in the header of the request. For details, see Risk Evaluations.
Jun 20, 2023 In MFA policies, you can now disable pairing for specific authentication methods. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices. See pairingDisabled in Device Authentication Policies.
Jun 19, 2023 To provide support for passkeys, Fido policies have been expanded significantly. For details, see FIDO Policies. Note that FIDO policy requests now use the endpoint environments/{{envID}}/fido2Policies and not environments/{{envID}}/fidoPolicies. In the framework of these changes, support was added for a new MFA device type called FIDO2. For details, see MFA Devices.
Jun 15, 2023 Requests that use the flows endpoint and the deviceAuthentications endpoint now include additional device status information in the response: usableStatus, pushStatus, and otpStatus. For details, see Flows and MFA Device Authentications.
Jun 12, 2023 PingOne MFA has moved to Firebase Cloud Messaging for sending push messages. This impacts the credentials you must enter when enabling push notifications for Google Play-based mobile applications. For details, see Application MFA Push Credentials.
Jun 1, 2023 We've fixed an issue with the Try a Request feature in the documentation. We've re-enabled this feature for all endpoints except the authorization endpoints (identified by the {{authPath}} variable). The Try a Request feature has always been blocked for these endpoints, due to a CORS constraint.
May 18, 2023 You can now choose to include the IP address of an actor and the user-agent HTTP header of an event in the source section of a subsciption audit event. See Create Subscriptions.
May 8, 2023 It is now possible to have one-time passwords delivered via voice to phone numbers that include extensions. For details on enabling support for phone numbers with extensions, see MFA Settings.
Apr 28, 2023 PingOne now supports a Language Translations service, which provides operations to view the custom string translations for a specified language and to update localized strings for specified user interface elements. For details, see Language Translations.
Apr 25, 2023 DaVinci no longer ignores the pi.flow OAuth property. For details about pi.flow, see the OpenID Connect/OAuth2 data model.
Apr 23, 2023 When creating notification policies, you can now use the quotas array to limit the use of email messages for pairing and authentication. For details, see Notification Policies.
Apr 19, 2023 For integrity checking on Android devices, PingOne MFA now uses Google's Play Integrity API. This requires you to provide additional information from your Google service account if you want to create or update an application that uses integrity checking. For the details of the new mandatory fields, see the Applications OIDC settings data model table in Application Operations and the Create Application (OIDC Protocol - Native App) sample.
Apr 14, 2023 PingOne now supports the Forms service, which provides tools for administrators to create custom forms presented to users during the authentication workflow. For details, see Forms and Forms Recaptcha.
Apr 3, 2023 When creating notification policies, you can now use the countryLimit object to limit the countries where you can use SMS and voice notifications. For details, see Notification Policies.
Mar 27, 2023 PingOne now supports the SCIM 2.0 identity management standard for provisioning users into PingOne Directory. Currently we support the /Users endpoint with basic SCIM to PingOne Directory attribute mapping. For details, see SCIM.
Mar 27, 2023 When creating or updating New Device risk predictors, you can now use the activationAt parameter to specify a date on which the learning process for the predictor should be restarted. This can be used in conjunction with the fallback setting (default.result.level) to force strong authentication when moving the predictor to production. For details, see Risk Predictors.
Mar 26, 2023 In addition to combining existing predictors, you can now include the following risk factors in your composite predictors: country, state, IP range, IP domain organization, ISP, target resource (application). For details, see Risk Predictors.
Mar 16, 2023 We've added new Sessions endpoints to Reset the Authentication Session by Session ID or Reset the Authentication Session by Session Token.
Mar 13, 2023 When defining the settings for mobile applications in an MFA policy, you can now use the new pairingKeyLifetime object to specify how long an issued pairing key can be used until it expires. For details, see Device Authentication Policies.
Mar 13, 2023 You can now define the number of consecutive push notifications that can be ignored or rejected by a user within a defined period before push notifications are blocked for an application. Use this setting to prevent attacks based on repeated push notifications that may lead users to eventually accept the authentication request. For details, see the documentation for the pushLimit object in Device Authentication Policies.
Feb 01, 2023 The platform now supports properties for enumerated values and regular expression validation in the schema data model. For details, see Schemas.
Jan 10, 2023 You can now configure Android applications to use Huawei Mobile Services. For details, see Application Operations and Application MFA Push Credentials.
Jan 10, 2023 You can now use the dataExplorations endpoint to generate reports of MFA devices. For details, see Reporting.
Jan 10, 2023 For notification templates of type "Push", it is now possible to specify a push category to control the type of banner that is displayed to the user. For details, see Notification Templates.
Jan 3, 2023 You can now use the riskPredictors endpoint to create New Device predictors, which allow your risk policy to take into account the risk associated with users trying to access applications from unknown devices or devices that have not been used in the recent past. For details, see Risk Predictors.
Jan 3, 2023 In MFA policies, it is now possible to specify how much time users have to respond to a push notification before it expires. This period can be defined separately for each mobile application included in the MFA policy. For details, see Device Authentication Policies.
Jan 3, 2023 The default method to use for MFA is now set at the MFA policy level rather than at the environment level. For details, see Device Authentication Policies.
Jan 3, 2023 It is now possible to block a user's MFA device, and to unblock a device that is currently blocked. For details, see MFA Devices.
Dec 15, 2022 It is now possible to use the API to unlock a device that was locked-out due to too many failed MFA attempts, even if the defined waiting period has not yet elapsed. For details, see MFA Devices.
Dec 15, 2022 It is now possible to use the gateways endpoint to create a RADIUS gateway. For details, see Gateway Management.
Dec 8, 2022 We've added properties to support applications using WS-Federation. See the Applications base data model and the Applications WS-Federation settings data model for more information.
Dec 2, 2022 We've added an email verification endpoint to verify a user's email through a verification code. See User Email Verification.
Nov 22, 2022 You can now use the hiddenFromAppPortal property to hide an application in the application portal, overriding your configured group membership access policy. See Applications base data model.
Oct 26, 2022 You can now use the nameFormat property to define the naming format for attributes other than Subject. See Applications attribute mapping data model.
Oct 26, 2022 We've added the initiateLoginUri and targetLinkUri properties to the Applications OIDC data model.
Oct 25, 2022 The Token Introspection Endpoint now supports authentication with a Resource ID and Secret. See POST Token Introspection (Resource ID and Secret) and Resource Secret.
Oct 21, 2022 You can now allow a wildcard character in the Redirect URI for OIDC applications. See Applications OIDC settings data model.
Oct 19, 2022 PingOne Risk now includes an SDK that allows you to obtain additional risk-related data and pass the data to the risk evaluation, resulting in improved detection. The riskEvaluations endpoint can now take the data provided by the SDK in a header called X-SDK-DATA-PAYLOAD. For details, see the documentation for creating risk evaluations.
Sep 28, 2022 To simplify automated testing of your applications, you can now create dedicated testing devices. When you use the API to send authentication requests to such a device, the OTP is not sent to the actual device, but instead is returned as part of the body of the response. See MFA Devices.
Sep 15, 2022 We've added support for the WS-Federation protocol to the Application Management service. This supports Microsoft's Office365 and Azure integration with PingOne. See Create Application (WS-Federation Protocol) for more information.
Aug 31, 2022 When using the mfaSettings endpoint to update MFA settings, you can now use pairing.pairingKeyFormat to specify the type of pairing keys that should be used - 12-digit numeric keys or 16-character alphanumeric keys. Existing environments will continue to use the 12-digit numeric keys unless changed. New environments will use the 16-character keys by default.
Aug 31, 2022 It is now possible to create composite predictors - for situations where you are interested in combining a number of risk predictors into a single predictor. See Risk Predictors.
Aug 26, 2022 The platform now supports adding custom claims to an OpenID Connect scope. See Resource Scopes.
Aug 18, 2022 We've added a default property to the Populations endpoint, enabling you to assign a default population to an environment. See Populations.
Aug 14, 2022 When creating or editing an MFA policy, you can now use the field mobile.applications[].integrityDetection to specify how registration and authentication attempts should be handled if a response is not received for device integrity: continue with the flow or block the user. For details, see Device Authentication Policies.
Aug 14, 2022 When defining a mobile application, you can now use mobile.integrityDetection.excludedPlatforms in conjuction with mobile.integrityDetection.mode to enable device integrity checking only for Android or only for iOS. For details, see Application Operations.
Aug 2, 2022 You can now use Kerberos to sign-on users. See Gateway LDAP data model in Gateway Management and the Sign On with Kerberos request.
Aug 2, 2022 You can now force a reset of the password identified by the user ID and environment ID without the administrator supplying a password. See Force Change Password request.
Aug 2, 2022 It is now possible to use the API to create and manage FIDO policies, which can then be included in device authentication policies. For details, see FIDO Policies and Device Authentication Policies.
Aug 1, 2022 It is now possible to use the riskPolicySets endpoint with conditions of type AGGREGATED_SCORES to create score-based policies. See Risk Policies.
Jul 18, 2022 For sign-on policies in PingOne, MFA steps are added now by referencing an existing MFA policy rather than having to define the specific authentication methods that are allowed for the policy. For details, see Sign-On Policy Actions.
Jul 14, 2022 The platform now includes PingFederate admin roles, allowing admins to SSO from PingOne into PingFederate with the appropriate permissions for their role. See Roles.
Jul 10, 2022 For organizations that prefer to maintain their own user device information, it is now possible to initiate authentication while providing the information necessary for contacting the user. See the documentation for the selectedDevice object in MFA Device Authentications.
Jul 7, 2022 It is now possible to create passwordless authentication flows that require only FIDO2 authentication with no need for the user to provide their username. To use this feature, use the rp.id property in the request body for deviceAuthentications. For details, see MFA Device Authentications.
Jun 6, 2022 You can now define notification policies to limit the use of SMS and voice messages for pairing and authentication. For details, see Notification Policies.
Apr 28, 2022 The platform now includes the PingOne Authorize API access management service, which provides tools to externalize the management and evaluation of access control policies for HTTP-based APIs. See PingOneAuthorize API Access Management.
Apr 25, 2022 MFA Native SDK v1.7.0 now supports authentication code flows for Android and iOS operating systems. See Authentication code flow. SDK v1.7.0 also supports elliptic-curve cryptography (ECC) for signing and verifying mobile requests. This feature uses iOS secure enclave capabilities.
Apr 25, 2022 The platform now includes endpoints that initiate an authentication code flow. See MFA Authentication Code. The platform includes a new uriPrefix property on the application's mobile object that specifies a valid app/universal link or app schema to enable direct triggering of the mobile application when scanning a QR code. See Application Operations.
Mar 11, 2022 The platform now requires a minimum password length of 8 - 32 characters. For more information, see Password Policies.
Mar 07, 2022 The platform now supports a hybrid flow authorization request, in which some tokens are returned from the authorization endpoint, and others are returned from the token endpoint. For more information, see GET Authorize (hybrid) and POST Authorize (hybrid).
Feb 09, 2022 The platform now supports a policy.id property for MFA devices that specifies the device authentication policy ID associated with the device resource. For more information, see MFA Devices and MFA Pairing Keys.
Feb 04, 2022 The platform now supports a PingFederate-SSO platform application, which is created automatically if the PingOne environment includes PingFederate. For more information, see Application Management.
Jan 13, 2022 Custom risk predictors cannot be referenced as an attribute in a placeholder details list (${details.<attribute>}). See Custom risk predictor conditions in Risk Predictors for more information.
Dec 27, 2021 The platform now supports configuring the whiteList property on a per risk predictor basis. For information about risk predictors that support the whiteList property, see Risk Predictors.
Dec 27, 2021 The platform now supports the User Location Anomaly risk predictor. See Risk Predictors.
Dec 23, 2021 For authorization requests that return an invalid request object error, the error message now includes additional details about the INVALID_VALUE. For example, the old detail message stated this: "The request parameter contains an invalid Request Object". The new detail message provides specific information about the validation error: "The request parameter contains an invalid Request Object: The token signature is invalid.".
Dec 17, 2021 The Integration Catalog has been updated to easily retrieve application integration information and assets.
Dec 17, 2021 The image service API now returns a regionalized URL for any new images uploaded. For example, if you are in the EU and use pingone.eu, then uploaded images will now be in this format "https://uploads.pingone.eu/environments/..." instead of "https://uploads.pingone.com/environments/..." . This regionalization is also applicable to uploaded images in the .asia and .ca regions. Old image URLs will still work as expected. For more information, see Images.
Dec 16, 2021 The platform now supports configuration of policies for MFA enrollment and authentication transactions in PingOne Flows.
The apiPath/environments/envID/deviceAuthenticationPolicy endpoint is deprecated, but still supported. No immediate code change are required, but it's recommended to change to the new apiPath/environments/envID/deviceAuthenticationPolicies endpoint.
See Device authentication policies that now supports the following operations:
Dec 15, 2021 The platform now includes endpoints that initiate and complete an MFA action without requiring a call to the PingOne authorize service. For more information, see MFA Device Authentications.
Dec 15, 2021 The platform now supports the ability to configure short codes and toll-free origination numbers to send SMS and voice notifications to recipients in multiple countries.
See the supportedCountries property in the Custom provider phone number properties table.
Dec 12, 2021 The platform now supports configuration of untrusted sender email addresses at the email notification template content level, when using a custom email sender.
See Content properties.
Dec 08, 2021 The platform now provides easier integration with custom providers' remote gateways, including support for dispatching voice notifications.
This implementation uses the GET and POST operations and customizable body and headers.
Basic and bearer authentication methods are supported.
See Phone delivery settings.
Dec 07, 2021 The platform now includes decision endpoints that allow efficient evaluation of policies developed in the PingOneAuthorize Policy Editor Service. For more information, see PingOneAuthorize Policy Decision Service.
Nov 08, 2021 The platform now supports a JSON array PATCH action to update targeted elements on a user object. For more information, see Update User (Patch JSON Array).
Oct 25, 2021 The notifications settings property, notificationsSettings.defaultLanguage, has been removed from the platform. When required, notifications use the environment's default language, which is set using the /environments/{{envID}}/languages endpoint. For information about notification content and language selection, see Runtime logic for content selection. For information about an environment's default language, see Language Management.
Oct 04, 2021 Ping Identity has added a Canada regional data center, that will provide enhanced performance and response on services for Canadian customers accounts hosted on this data center.
Canada data center domains:
  • Management APIs: api.pingone.ca
  • Authentication and authorization APIs: auth.pingone.ca
Sep 30, 2021 The platform now supports the Identity Data Read Only Admin role. See Roles.
Sep 30, 2021 The platform now supports custom risk predictors. See Risk Predictors.
Sep 2, 2021 The platform now supports connecting to external LDAP directories to validate user credentials. See Gateway Management.
Aug 31, 2021 The platform now supports configuration of your own provider for dispatching SMS notifications. See Phone delivery settings.
The phoneDeliverySettings.provider field now supports the new CUSTOM_PROVIDER valid value.
The new POST Create Phone Delivery Settings and PUT Update Phone Delivery Settings operations use the new custom provider phone delivery settings properties:
  • name
  • provider
  • authentication object
  • requests object
  • numbers object

Note: This implementation uses the POST operation and non-customizable body and headers. It requires customers to create a gateway that receives these requests in their simple, static format, and translates those requests into their custom provider’s supported SMS format.
Aug 12, 2021 From MFA Native SDK v1.6.0, the platform supports mobile device integrity checks.
  • The native device’s rooted property is deprecated, and is replaced by deviceIntegrityState. See Native Device Properties in MFA devices.
  • The application’s packageName and bundleId properties have been moved to the new mobile object. See Application Operations.
  • The pairing key object has a new error property, and the status property has the new FAILED value. See MFA pairing keys.
Jul 29, 2021 The following properties have been added to the risk evaluations details data model: state, city, previousSuccessfulTransaction.state, previousSuccessfulTransaction.city. See Risk evaluations.
Jul 26, 2021 The platform now supports the Credentials Issuance service, enabling you to create custom verifiable credentials for users. See Credentials Issuance.
Jul 14, 2021 The platform now supports configuration of your MFA authentication methods according to your security policies, including passcode refresh time (mobile applications), passcode retry attempts, passcode lifetime duration, and device block duration times. See Device authentication policies.
Jun 30, 2021 The platform now supports dispatching SMS and voice notifications via your organization's own Syniverse account in place of Ping Identity's account or your own Twilio account.
The phoneDeliverySettings.provider field now supports the new CUSTOM_SYNIVERSE valid value.
The fallback option uses the smsProvidersFallbackChain property. For more information see Phone delivery settings. To configure an SMS and voice provider fallback chain see Notifications settings.
Jun 30, 2021 The platform now supports pairing a phone number as an MFA method using a voice call OTP, and subsequent voice call OTP authentication notifications to paired phone numbers.
The following new operations were added:Existing services have been extended to include voice OTP:
  • Support for voice OTP as an MFA method in a sign-on policy. See the voice and voice.enabled properties in the MULTI_FACTOR_AUTHENTICATION action data model in Sign-On Policy Actions.
  • Support for voice as one of the Notification Template's deliveryMethods, and custom notification with the creation of an SMS, voice or email MFA device. For more information, see Custom device pairing notification with device creation.
May 06, 2021 The platform now supports just-in-time provisioning of new users who authenticate with a registered authoritative external identity provider. See Identity Provider Management and Users.
May 05, 2021 The platform now provides the number of OTP attempts remaining in the error message detail as part of the Check One-Time Passcode action and Activate MFA User Device action.
Apr 13, 2021 The platform now provides a Risk Advanced Predictors endpoint to include advanced predictor criteria for risk policies. For more information, see PingOne Risk, Risk Advanced Predictors, and Risk Policies.
Apr 08, 2021 If you attempt to create or update a custom content for an existing combination of template, locale, deliveryMethod and variant, you now get an INVALID_DATA/UNIQUENESS_VIOLATION error.
Mar 24, 2021 The platform now provides a sign-on policy action that bypasses the PingOne sign-on screen and immediately redirects the user to an external identity provider's sign-on workflow to authenticate. For more information, see Sign-On Policy Actions and External Authentication.
Mar 19, 2021 The platform now provides a user account management endpoint to unlock a user account. For more information, see User Accounts, Users, Sign-On Policy Actions, MFA Settings, and Flows.
Feb 23, 2021 The platform now supports the ability to prompt end users with your own legal text during registration and sign on. The platform records a user's active consent to the document before proceeding with the flow. For more information, see Agreement Management, User Agreement Consents, Sign-On Policy Actions, and Flows.
Feb 23, 2021 The platform now supports text and language customization for all end user interfaces and notifications. In this initial release, it supports the new Agreements (terms of service) feature. For more information, see Language Management.
Feb 03, 2021 The platform now supports groups for users. For more information, see Groups.
Feb 03, 2021 The platform now includes optional accessControl properties on applications that, when set, specify the conditions that must be met by an authenticating actor to access the application. For more information, see Control access to applications through roles and groups.
Feb 02, 2021 The platform now supports multiple custom contents for each template + deliveryMethod + locale combination with the variant property. For more information, see Notifications templates.
Feb 02, 2021 The platform now supports a custom notification with the creation of an email or SMS MFA device. For more information, see Custom device pairing notification with device creation.
Feb 1, 2021 The platform now includes the PingOne Verify APIs, and the PingOne Verify native SDKs.
Jan 19, 2021 The platform now includes endpoints to read and update MFA settings. For more information, see MFA Settings.
Jan 19, 2021 The platform includes support for FIDO2 bound biometrics devices and FIDO2 or U2F security key devices. For more information, see FIDO2 Devices.
Jan 11, 2021 The platform now supports device ordering to create a default active device. For more information, see Device order.
Jan 08, 2021 The platform now supports external registration, which provides a sign-on action to register a user using an external identity provider's registration workflow. For more information, see Flows and Sign-On Policy Actions.
Dec 30, 2020 The platform now supports a maximum allowed devices setting for paired devices and a device nickname property used during authentication. For more information, see Maximum allowed devices and Device properties.
Dec 14, 2020 The platform now supports risk policy sets and risk evaluations. For more information, see PingOne Risk.
Dec 14, 2020 The platform now supports using the token endpoint so that the client can make a token exchange request to the PingOne authorization server. For more information, see Token Exchange (Gateway Credential).
Dec 09, 2020 The application protocol data model property no longer supports the NONE option. For more information, see Application Operations.
Dec 03, 2020 Notifications content variables are now case insensitive. For more information, see Notifications Templates.
Oct 15, 2020 The platform now supports an alerting service that delivers high-level email warnings about resource states. For more information, see Alerting.
Oct 13, 2020 The platform now supports a Time-based One-time Password (TOTP) authenticator application device type. For more information, see Create MFA User Device (TOTP) and Sign-on Policy Actions.
Sep 29, 2020 The platform now supports the PingOne MFA product. For more information, see Getting Started with PingOne MFA.
Sep 22, 2020 The platform now supports the ability to select and customize the branding themes that you can apply to your sign-on screens. For more information, see Branding.
Sep 21, 2020 The platform now supports self-management access control scopes that allow organizations to specify which user profile attributes are accessible to end users. For more information, see Access services through scopes and roles and Resource scopes.
Sep 14, 2020 The platform now includes endpoints to manage Yahoo, Microsoft, GitHub, and PayPal external identity provider configurations. For more information, see Identity providers.
Jul 21, 2020 The platform now supports the ability to configure a trusted email domain for each environment. A trusted email domain with its associated email addresses enable PingOne to send emails on your organization’s behalf. For more information see Trusted email domains and Trusted email addresses.
Jul 07, 2020 The platform now supports configuration of sign-on policies to determine whether MFA is required for authentication requests detected as originating from an anonymous network such as an unknown VPN, proxy or anonymity communication tool such as Tor. It is possible to exclude specific IP addresses using a whitelist. See the anonymousNetwork condition in the Condition Variables table in the Sign-on Policy Actions page.
Jun 25, 2020 The platform now includes endpoints to manage Apple external identity provider configurations. For more information, see Identity providers.
Jun 24, 2020 The platform now includes endpoints to manage Amazon external identity provider configurations. For more information, see Identity providers.
Jun 24, 2020 The platform now includes endpoints to manage Twitter external identity provider configurations. For more information, see Identity providers.
Jun 16, 2020 The platform now supports despatching SMS notifications via your organization's own Twilio account in place of Ping Identity's account. This also allows for the option of falling back to Ping's account in the event of notification failure, using the new smsProvidersFallbackChain property. For more information see Phone delivery settings. See Notifications settings to configure an SMS provider fallback chain.
Jun 16, 2020 The platform now supports transaction approval when strong authentication is required for elevated security for a high value transaction, or high risk resource or service. This includes use of the new request property in the following OIDC operations: GET Authorize (authorization_code), POST Authorize (authorization_code), GET Authorize (implicit) and POST Authorize (implicit). Transaction approval also permits use of the new allowDynamicVariables property in Notifications templates.
Jun 16, 2020 From Native SDK v1.3.0, the platform supports extra verification on device authorization. For more information see the extraVerification property in Sign-on policy actions.
May 05, 2020 The platform now provides an interface for third-party auditing tools to subscribe to and consume PingOne audit activity events. For more information, see Subscriptions (webhooks).
Apr 30, 2020 The platform now supports a token revocation endpoint. For more information, see Token revocation.
Apr 15, 2020 The platform now supports an identity-provider initiated SAML authentication single sign-on flow. For more information, see SAML 2.0.
Apr 15, 2020 The sign-on policy service now includes an IDENTIFIER_FIRST sign-on policy action. For more information, see Sign-on policy actions.
Apr 03, 2020 The sign-on policy service now includes a PROGRESSIVE_PROFILING sign-on policy action. For more information, see Sign-on policy actions.
Apr 03, 2020 The licenses and capabilities services now include properties that designate whether the license allows the creation of custom domains. For more information, see Licensing and Capabilities.
Apr 03, 2020 The flow service has changed so that a session token cookie is set only after the identity of the user has been partially established. For more information, see Identity providers.
Apr 03, 2020 The platform now includes endpoints to manage OpenID Connect external identity provider configurations. For more information, see Identity providers.
Mar 31, 2020 The platform now supports configuration of sign-on policies to determine whether MFA is required for authentication requests detected as having high-risk IP reputation and geovelocity anomalies. See the geovelocity and IP reputation Condition variables on the Sign-on policy actions page.
Mar 31, 2020 From Native SDK v1.2.0, the platform includes the ability to get logs from authenticating user native devices for investigation and support. See Devices API operations on the Devices page.
Mar 31, 2020 From Native SDK v1.2.0, the platform includes the ability to send logs from authenticating user native devices to the PingOne server, for investigation and support.
Mar 31, 2020 From Native SDK v1.2.0, the platform supports automatic device authentication. See PingOne Native SDK flows.
Mar 13, 2020 The platform now includes an identity propagation API that provides for configurable and audit-capable propagation of identities and their attributes between identity stores owned or managed by a customer. For more information, see Identity propagation.
Mar 11, 2020 The platform now includes an identity provider discovery login flow that initiates actions to identify the user and determine the applicable authentication methods for this user. For more information, see Identifier first action and Get a flow.
Mar 11, 2020 The platform now includes a progressive profiling authentication flow that prompts users to provide additional data at sign on. For more information, see Progressive profiling action and Submit profile data.
Feb 19, 2020 The set password action now includes an optional bypassPolicy property that specifies whether the user's password policy should be ignored. For more information, see Set password.
Feb 10, 2020 The platform now includes an endpoint to view and license capabilities. For more information, see Capabilities.
Jan 13, 2020 The platform now includes an endpoint to view and update the name property value for a license. For more information, see Licensing.
Dec 17, 2019 The platform now supports a token introspection endpoint. For more information, see Token introspection.
Dec 10, 2019 The platform now supports password policy customization. For more information, see Password policies.
Dec 10, 2019 The platform now supports configuration of a Proof Key for Code Exchange (PKCE) authorization workflow. For more information, see OpenID Connect/OAuth 2 and Configure a PKCE authorization workflow.
Dec 10, 2019 The platform now supports custom domains. For more information, see Custom domains.
Dec 10, 2019 The platform now includes endpoints to manage LinkedIn external identity provider configurations. For more information, see Identity providers.
Dec 10, 2019 The platform now includes endpoints to customize ID tokens for a OIDC applications. For more information, see Attribute mapping.
Dec 09, 2019 The Native SDK supports automatic enrollment through OIDC authentication.
Oct 10, 2019 The Native SDK sample app for Android now has notification banners.
Oct 10, 2019 The Native SDK Android component dependencies have been updated: the Nimbus library has been replaced by Jose4J. See Pingone Native SDK > Android > Set up a native app using the PingOne SDK sample code > Add the PingOne SDK component into your existing project.
Oct 10, 2019 The iOS Native SDK API now requires Swift 5.1. See Pingone Native SDK > iOS > Set up a native app using the PingOne SDK sample code > Xcode integration for software prerequisites.
Oct 10, 2019 Logs appeared in the Android developer console. This has been resolved so that they no longer appear. (P14CMFA-3242)
Oct 03, 2019 The platform now includes endpoints to view authentication statistics on a per application basis. For more information, see Authentications per application.
Aug 30, 2019 The platform now includes endpoints to manage Google external identity provider configurations. For more information, see Identity providers.
Aug 30, 2019 The platform now supports access token customization. For more information, see Access token customization.
Aug 19, 2019 The platform now includes a basic password policy to allow for maximum customer flexibility. For more information, see Password policies.
Aug 14, 2019 Sign-on policy action condition attributes now require camelCase syntax for attribute names (for example, ipRange, secondsSince). For more information, see Sign-on policy actions.
Jul 31, 2019 The platform now supports the refresh_token grant type. For more information, see Access tokens and ID tokens and Obtain an access token.
Jul 31, 2019 The platform now supports a native SDK that allows developers to send push notifications to custom native applications for multi-factor authentication (MFA). For more information, see Pairing keys, Android PingOne Native SDK API, and iOS PingOne Native SDK API.
Jul 31, 2019 The following template IDs (see Notifications templates) have changed:
  • offline_pairing has been renamed to device_pairing
  • offline_authentication has been renamed to strong_authentication
Calls to the GET {{apiPath}}/environments/{{envID}}/templates endpoint will return the new template IDs, instead of the old ones. The deprecated offline_pairing and offline_authentication template IDs are still supported for backward compatibility, but will be unsupported at a future date.
Jul 02, 2019 The platform now includes endpoints to manage external identity provider configurations that enable social login and inbound SAML login features in PingOne. It also includes endpoints to manage a user’s links to external identity provider accounts. For more information, see Identity providers and Linked accounts.
Jun 25, 2019 The platform now includes endpoints to get information about the licenses associated with an organization. For more information, see Licensing.
Jun 25, 2019 The platform now includes endpoints to get information about active identity counts and total identity counts. For more information, see Active identity counts and Total identities.
Jun 13, 2019 The file import feature is temporarily disabled. It will be enabled in a future release.
Apr 15, 2019 The platform now supports a passwordless authentication flow. For more information, see Sign-on with a username and Configure a passwordless sign-on policy.
Apr 01, 2019 PATCH requests that modify custom JSON user attributes are replaced completely. For more information, see Users: Partial update.
Apr 01, 2019 Sign on policy actions now support a policy condition language that allows both logical and data rules to construct a policy condition statement. For more information, see Sign-on policy action conditions.
Mar 25, 2019 Platform scopes, such as p1:read:env:user, p1:create:env:device, and p1:update:env:population, have been removed. In order to access platform APIs, you must create a new WORKER application type. For more information, see Access through scopes and roles.
Mar 25, 2019 Scopes with “self” in the name have been renamed. Example: p1:reset:self:userPassword is now p1:reset:userPassword. For more information, see Access through scopes and roles.
Mar 01, 2019 The SAML attribute mappings data model now includes a mappingType attribute to identify CORE, SCOPE and CUSTOM mapping types. For more information, see Attribute mapping.
Feb 18, 2019 The following templates are available for use with notifications templates: verification_code_template, recovery_code_template, offline_authentication, and offline_pairing. For more information, see Notifications templates and Notifications settings.
Jan 28, 2019 The flow service no longer uses the /step/{{stepID}} sub-resource, and it no longer shows multiple statuses and nested embedded resources. The status property in the flow response contains all information about the flow's current state. For more information, see Flows.
Jan 22, 2019 Audit reporting supports a POST operation to retrieve audit events without exposing sensitive or personal filtering information in a GET request URL. The required SCIM filtering expression is specified in the POST request body. For more information, see Get audit activities using POST.
Jan 21, 2019 The data model for SAML application settings requires a leading dollar sign ($) when specifying the expression in the value attribute. For example, "value": "${user.username}". For more information, see SAML application attribute mappings.
Jan 11, 2019 The GET {{apiPath}}/environments/{{envID}}/activities endpoint no longer supports the in (includes) SCIM operator. For more information, see Audit activities and events.

More information

For more information about PingOne product updates, see Release Notes.

Working with PingOne APIs

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment. See also Using the PingOne APIs.

PingOne API domains

This section discusses how PingOne API regional endpoints are entered in the domain name system (DNS). In DNS, and in our endpoints, the domain part of the uniform resource locator (URL) comprises three parts separated by periods, such as api.pingone.com: one of our service-specific subdomains, our PingOne domain name of pingone, and one of our top level domains.

We use Postman variables to manage this variety of domain parts in PingOne API endpoints. The later discussion is correct regarding the domain part that the variables evaluate to. However, to ease maintenance, the Postman environment template you get when you Download the PingOne Postman collections uses variables to isolate the TLD from the rest of the domain part and to isolate the domain part from the rest of the endpoint.

The environment template has a path variable for each subdomain. Each path variable uses another variable, {{tld}}, for the top level domain (TLD). Such as https://api.pingone.{{tld}}/v1 for {{apiPath}}. The tld variable is first in the environment template that you downloaded.

The table below shows the top level domain value for each region. To change your region, simply change the default {{tld}} value from com to your region's TLD.

Region Top level domain
North America region (excluding Canada) com (default)
Canada region ca
European Union region eu
Asia-Pacific region asia
Australia region com.au

The PingOne API includes the following domains:

Domain Postman path variable Description
api.pingone.{{tld}} {{apiPath}} The primary domain for calling PingOne Management API resource server.
auth.pingone.{{tld}} {{authPath}} The authorization and authentication server domain called to request the access token required to authenticate PingOne API requests.
orchestrate-api.pingone.{{tld}} {{orchestratePath}} The primary domain for calling the PingOne DaVinci Management API resource server.
scim-api.pingone.{{tld}} {{scimPath}} PingOne API service for Cross-domain Identity Management (SCIM).

The {{...Path}} variable in the sample requests stand for the PingOne service endpoint. See Public endpoints in the PingOne for Developers Foundations guide for more information.

The Try a Request feature

Our documentation for the PingOne APIs includes an interactive Try a Request feature. Try a Request enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

Requests in Authentication and Authorization APIs do not have the Try a Request feature due to a Cross-Origin Resource Sharing (CORS) constraint.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. See Postman Collection-Level Authorization for more information.

Forward compatibility guidance for PingOne client developers

This section provides guidance on what PingOne API client developers should do to maintain forward compatibility of their client applications as PingOne APIs evolve. PingOne is a continuously developing platform, and developers must be aware of non-breaking changes to the APIs and how to prepare for these inevitable changes. PingOne will rarely, if ever, introduce a breaking change; however, when that happens, there will be notifications or deprecation messages to inform developers. For non-breaking changes, client developers must ensure that their apps will function as expected after the following API changes occur.

Non-breaking API changes

Client applications should be resilient to additions of new optional properties in request, response, and event payloads. The following list of enhancements occur regularly to the Pingone platform API.

Related resource links

The addition of new related resource links added to responses should not cause application breaks in your client environments.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda"
        },
        "license": {
            "href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda/licenses/3f06970a-3235-46cb-b46f-cf6dfee2bb84"
        },

Almost all PingOne API responses include a _links section that lists related resources as HAL (Hypertext Application Language) links, and these lists change as the platform adds new resources (and new relationships). For common endpoints, the list of HAL links changes often.

New optional properties

The addition of new (optional) properties added to request, response, and event payloads should not cause application breaks in your client environments.

PingOne API endpoints, even those that have been part of the platform since its inception, can receive additional optional data model properties as the platform matures. Client application developers must configure their client environments to accommodate new optional properties in requests and support new returned properties in endpoint responses.

New content-types or content-language formats

The addition of new content-types or content-language formats of the same resource should not cause application breaks in your client environments.

The platform API includes endpoints that support multiple content types. Client application developers must configure their application environments to accept supported media types for the endpoint. For example, the following request shows a new action on the /{{envID}}/flows/{{flowID}} endpoint that supports a device authorization grant. Your client environment should support the new content type, application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json.

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json' \
--data-raw '{
    "userCode": "{{userCode}}"
}'

In addition, the PingOne API might (over time) return new content types for a given resource. If a client is retrieving a resource without specifying the exact type that it is expecting, then it must be able to tolerate processing any response content type that satisfies the Accept HTTP header.

For example, a client issues this request:

curl --location --request GET '/some/resource' \
--header 'Accept: */*'

Initially, GET /some/resource is represented by a Content-Type: application/json response, which satisfies the request's Accept: */*. A client could assume that this response is always application/json and only have code to process such responses.

However, at some later date, GET /some/resource supports a new Content-Type: text/html response, which also satisfies the request's Accept: */*. The platform does not guarantee the choice of Content-Type when multiple values satisfy the request. In such cases, the client could start receiving Content-Type: text/html and process this response incorrectly, expecting it to be JSON.

In cases where clients can receive any content type that satisfies their request’s Accept: */* header, the client must be configured to handle any content type that is returned. Or, preferably, clients should be configured to be as specific as possible about the content type they are able to accept.

New HTTP methods

The addition of new supported HTTP methods added to a resource should not cause application breaks in your client environments.

Client application developers must configure their application environments to accommodate new HTTP methods added to a platform service. For example, adding a new PATCH operation to an endpoint should be supported in your client environments.

Third-party libraries

Some third-party libraries deployed in your client environment can cause failures as a result of the non-breaking API changes listed above. In such cases, configuration of the library objects can resolve the issue.

For example, if your application environment uses the Jackson library to serialize or map Java objects to JSON, it is recommended that you update the object mapper setting responsible for deserializing API responses to prevent deserialization errors when new properties are added to the API response. The recommended setting is: new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);. (Jackson's default setting is true.)

As a backup, you can also annotate Jackson library objects with the @JsonIgnoreProperties(ignoreUnknown = true) property to prevent deserialization errors. Conservative developers may choose to employ both strategies.

Protocol for breaking changes

Ping Identity will only support the current release of the platform APIs.

APIs and resources that are made generally available to all customers for Ping Identity’s multi-tenant hosted service products are designed to evolve in a non-breaking fashion rather than rely on versioning to change. In the case of a breaking change that requires an API or a resource to be versioned, the following describes the Ping Identity version support lifecycle:

  • The current version of the API or resource will be supported;

  • Once a new version of the API or resource is released, the previous version will also be supported for one (1) year; and

  • Anytime after this one (1) year period, previous versions of the API or resource will be removed.

Retries: Best practice for managing transient API errors

Transient API errors occur because of temporary service interruptions such as network issues, rate limits, server congestion, and other similar occurrences. This topic outlines the recommended best practices for implementing retry-handling logic to maintain resiliency in the applications and integrations with PingOne.

These HTTP status codes indicate temporary issues that can resolve over time, making them ideal candidates for automatic retries by a calling client.

HTTP status code Description
408 (Request Timeout) The server took too long to respond to the client request, possibly caused by a weak or slow connection to the client application.
429 (Too Many Requests) Rate limiting controls denied the request, often because the user is over quota for the request. Retry after the delay specified in the Retry-After header. See PingOne Platform Limits in the PingOne admin documentation for more information.
500 (Internal Server Error) There was an unexpected server-side error encountered while processing the request.
502 (Bad Gateway) Suggests a temporary network issue or service stack disruption caused by a communication problem between servers.
503 (Service Unavailable) The server cannot process the request, possibly resulting from a temporary service outage or in-progress deployment.
504 (Gateway Timeout) A downstream server (for example, DNS) didn't respond in time to complete the request.

For more information about these status codes, see MDN Web Docs HTTP response status codes.

Retry-handling logic with exponential backoff and jitter

Do not simply create a loop that rapidly re-submits the same request over and over. You could unintentionally end up with a status 429, trigger rate limiting, or worse have your IP address blocked. Instead, implement an exponential backoff with jitter that gradually increases the time between retry attempts. Start small and increase exponentially until reaching maximum delay. This allows the server or network time to recover, and your application will get the response it needs.

For example, you can increase the number of seconds between retries in powers of two. If you add jitter, which involves adding randomness to those retry delays, this will randomize backoff retry delays to avoid "retry storms" when multiple clients are in use simultaneously.

// Pseudo code
// Example of an exponential backoff calculator
function calculateExponentialBackoff(attempt, baseDelay) {
    jitter = random(0, 100); // Add random jitter
    return baseDelay * (2 ** attempt) + jitter;
}

Honor the Retry-After header

Status codes 429 and 503 often include a Retry-After header that specifies one of two things, depending on the status code. For a 429, it specifies how long the client should wait before retrying the request, designated in number of seconds. For these cases, your retry handler must wait for the amount of time provided by the service.

For a 503 status code, the Retry-After header specifies when the service is expected to be available, designated in a date format. In both cases, the Retry-After header specifies when your app can reasonably make the request again. You need to do some math on the available date to figure out when you can try again. Or, if the retry delay is too long, then return a friendly error message to the client.

//Pseudo code
//Example of using the Retry-After header
if response.status == 429 or response.status == 503:
    retryAfter = response.getHeader("Retry-After");
    if retryAfter exists:
        wait(retryAfter);
    else:
        delay = calculateExponentialBackoff(attempt, baseDelay);
        wait(delay);

Don't make retry handling a catchall

It's good practice to avoid a catchall approach to errors, particularly if you are implementing retry logic in your API calls. The goal is to create resiliency in your application and provide the best user experience. Do not try to handle all status codes in the same way. The status codes outlined above that support retry logic mean different things with respect to how you should handle them.

The following is an example of an anti-pattern that could result in unintended bad consequences.

//Psuedo code
// Example of bad practice 
switch(statusCode) {
    case 408:
    case 429:
    case 500:
    case 502:
    case 504:
    case 503:
        //callout to service 
    default:
        //catchall for other status codes
}

Fail gracefully

If you reach the maximum number of retries without a successful request, it's important to consider how you handle the error. You need to take into account the user experience as well as your business requirements.

Don't return raw error responses to the user. Provide a useful, friendly error message with instructions on how to retry later or who to contact. If there are business implications to not making a successful request, first consider what operations might need to be rolled back, and any logging that should occur, before or simultaneously with your client error message (particularly in authentication and authorization transactions). You might need to revoke tokens or sessions, depending on your use case.

Security considerations

To avoid exposing your applications to vulnerabilities or attacks, it is important to design your retry handler properly. The following factors should be considered.

  • Maximum retry counts

    If your retry logic supports an unlimited number of retries, you could expose your application to resource exhaustion attacks. Attackers can use your application as a proxy for denial of service (DoS) attacks against PingOne APIs or as a conduit for brute force credential-stuffing attacks.

    Consult with your app owners and security teams to determine a reasonable number of retries. Set that as the maximum number of retries in your retry handler in a way that cannot be overridden.

  • Validate reasonable Retry-After limits

    Similar to the best practice of validating input data at the client and server, you should also validate the Retry-After header in API responses when the status code is 429 or 503. Man-in-the-middle attacks could result in manipulation of the response headers, and an attacker could reset the value to 1, causing your application to retry too often and get rate limited, or worse, have your IP address blocked. Likewise, attackers can reset the value to an extremely long wait time, like 172800 (2 days), causing your customers to abandon your application before a transaction is completed.

    If no Retry-After header is present, make sure you have reasonable values set in your exponential-backoff variable number of seconds to avoid rate-limiting, IP blocking, or retry storms.

  • Check for token expiration

    If your application is retrying requests, keep checking the HTTP status code in case it changes to a 401 (unauthorized), or 403 (forbidden). During your retry attempts, your token could expire, and you should switch to re-authentication before trying again. If you're using OAuth/OIDC, and depending on your security requirements, you have options for silent authentication with the prompt=”none” parameter, the login_hint_token request parameter, or using refresh tokens to get a new token before retrying. These options provide a better user experience rather than forcing users to login again.

  • Alert excessive failures

    Monitor, log, and alert the number of attempts a user or customer submits while using your application to retry these API calls (if you have that capability from your client application). It could be a sign of a misuse or abuse case you need to handle.

Sample retry handler

The following psuedo code sample shows these retry logic best practices.

// Pseudo code
//Example of retry logic
function callApiWithRetry(apiEndpoint, maxRetries = 5, baseDelay = 1000) {
    let attempt = 0;
   
    while (attempt < maxRetries) {
        response = makeApiCall(apiEndpoint);

        // Success Case
        if response.status == 200 || response.status == 202:
            return response.data;

        // Handle Transient Errors
        if response.status in [408, 500, 502, 504]:
            delay = calculateExponentialBackoff(attempt, baseDelay);
            wait(delay);

        // Handle Rate-Limiting
        else if response.status == 429 or response.status == 503:
            retryAfter = response.getHeader("Retry-After");
            if retryAfter exists:
                wait(retryAfter);
            else:
                delay = calculateExponentialBackoff(attempt, baseDelay);
                wait(delay);

        // Handle Authentication Failures
        else if response.status == 401 or response.status == 403:
            refreshToken(); // Secure token refresh or re-authentication
            continue;

        // Handle other errors (No retries)
        else:
            handleError(response); // Sanitize and log the error
            throw Error("Request failed with status code: " + response.status);
       
        // Increment Retry Counter and Monitor
        attempt += 1;
        monitorRetries(apiEndpoint, attempt); // Security monitoring for abnormal retry behavior
    }
   
    // Fail Gracefully After Max Retries
    throw Error("Max retries reached. Request failed.");
}

function calculateExponentialBackoff(attempt, baseDelay) {
    jitter = random(0, 100); // Add random jitter
    return baseDelay * (2 ** attempt) + jitter;
}

Accounting for Latency

API clients can experience latency when creating resources across services in the PingOne platform multi-region architecture, where the newly created resource has not propagated through the system to allow for the successful completion of a follow-up request. For example, if you create a resource with one internal service, it is possible that other internal services might not be aware of that new resource in time for your code's next step. An immediate call to the second resource can fail. Given this potential for latency, all applications should be written to retry the request.

The primary areas that experience latency are:

  • Applications and Secrets

    Latency occurs when you create an application and then try immediately to retrieve the system-generated secret.

  • Applications and Scopes

    Latency occurs when you create an application and then try immediately to retrieve its resource access grants.

  • SAML configuration and attributes

    Latency occurs when you create a SAML configuration and then try immediately to retrieve its attribute mappings.

  • Environments, role assignments, and applications

    Latency occurs when you create an environment and then try immediately to retrieve its role assignments or add an application to the new environment.

  • Populations and role assignments

    Latency occurs when you create a population and then try immediately to retrieve its role assignments.

Integrations

For information about integrating PingOne services with other Ping Identity products, see the following integration guides:

Integration Catalog API

The PingOne integration catalog API enables developers to discover and retrieve integration metadata and download integration kits as a compressed file. For more information, see Integration Catalog. For use cases, see the Workflow Library.

Postman and the PingOne APIs

We use Postman to create our PingOne API docs, and have supplied our Postman collections for you to download. There's also an accompanying Postman Environment template already populated with the variables used in the collections.

If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman, either locally, or in your browser.

See The PingOne Postman collections for the collections you can download or fork.

For more information about our Postman environment variables, see The PingOne Postman environment template.

You'll also find all of the Postman collections for our documented PingOne use cases in our Workflow Library.

The PingOne Postman collections

You can get here the PingOne Postman collections used for the Getting Started workflows, as well as the collections for all of our Platform APIs. You've two methods for retrieving a Postman collection into your workspace:

  1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If we update the source collection, you can pull those changes into the fork in your workspace.

  2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve a collection

Refer to The PingOne Platform collections on this page.

  1. Click the collection's Run In Postman button.

  2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

    RunInPostman

  3. Follow the on-screen instructions to fork or import the collection. You're prompted to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a selected workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you'll see Pull changes on the context menu. When you click Pull changes, Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also elect to watch the collection, you'll receive notifications when the source changes.

If you import a collection, a copy is created in the selected workspace with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and use only some requests in a collection, a link back to the source is not needed.

You're not limited to choosing one method or the other. You can fork a copy to track the source and import a copy for experimentation, if you like.

The PingOne Platform collections

These Postman collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne Platform APIs.

Collection Description Retrieve
Platform Postman requests for the PingOne platform API. Includes all environment variables. No example responses to make it easy to get started. Run In Postman
Platform Postman requests for the PingOne platform API. Includes all PingOne Platform API Reference documentation and example reponses. No environment variables are included. Run In Postman

For more information about the Postman environment variables included when you download or fork one of our Postman collections, see The PingOne Postman environment template.

The PingOne Postman environment template

Our Postman collections use variables in the request URLs to specify the UUIDs for PingOne resources. When you click the Run in Postman button for a collection, these environment variables are included in your download or fork. Use these environment variables as a template to assign your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, see the following topic in the Postman documentation: Environments in Postman.

POST requests in the PingOne Postman collections that create a resource and return a resource ID include a Postman script. This script automatically adds a resource variable to your active Postman environment, and uses the newly created ID as the value.

For example, the following request creates a new user. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/users

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top-level domain (TLD) associated with your organization. See Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you'll want to add your environment's UUID to your active Postman environment as the value for the {{envID}} variable.

Requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne Postman collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request shown above:

POST {{apiPath}}/environments/{{envID}}/users

If the request is successful, Postman adds a {{userID}} variable to the current Postman environment automatically, and associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It's important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. You'll want to pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud, and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman doesn't copy it to the current value or use the initial value in the request, the request simply fails. In this case, you need to manually copy the initial value to the current value.

When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the Postman cloud impacts security. These initial values are available to anyone who has access to the workspace. If a workspace is public, you have a security issue.

Postman's recommended solution to exposing secrets is to Store secrets in your Postman Vault. Remember that Postman uses only current values in requests.

Variables you must value

When you download or fork a PingOne Postman collection, your workspace receives a set of Postman environment variables for you to use as a template. The variables that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. Our script associated with the request (shown on the request's Scripts tab) inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne do not have their values inserted automatically. You must manually add the correct value to these variables before making any requests in Postman:

Postman variable PingOne resource
adminAppID The Client ID of the Worker app you created Create an admin Worker app connection.
adminAppSecret The Client Secret of the Worker app created.
adminEnvID The ID for the environment in which your Worker app resides.
envID The ID for the environment in which you are running your Postman API requests.
orgID The ID for your organization. In the PingOne admin console, select Environment and click Properties to view your organization ID.
tld The top-level domain to use for your environment. This is used in URLs containing apiPath, authPath, orchestratePath, and scimPath.
apiPath The regional domain for the PingOne management server (https://api.pingone.{{tld}}/v1).
authPath The regional domain for the PingOne authorization and authentication server (https://auth.pingone.{{tld}}).
orchestratePath The regional domain for the PingOne DaVinci management server (https://orchestrate-api.pingone.{{tld}}/v1).
scimPath The regional domain for the PingOne SCIM management server (https://scim-api.pingone.{{tld}}).

Application Management

Application resources define the connection between PingOne and the actual application (also known as a client connection). The application type you choose to create includes default settings that you're free to change. For example, you can configure the settings for a Single-Page application to match the settings for a Web application. This is by design for maximum flexibility.

Learn more in Applications in the PingOne admin guide.

When you make a request to create a new application, you must specify the type property that specifies one of the following application types:

  • Web application

    A browser-based application with a server-side component, such as ASP, CGI, JSP/Java, Node.js, or Ruby on Rails applications.

  • Native application

    An application that is installed and run directly on the local operating system, like Java, Objective-C, Swift, or React applications. Native applications are typically intended for mobile devices. These native applications are optionally configured using the mobile property.

  • Single-Page application

    A browser-based application that runs on the front-end with no server-side component, such as Sencha Touch, AngularJS, and React applications. A single page application runs on the client side after it loads, so it cannot keep a client secret.

  • Non-interactive

    A web application that does not require user interaction through the web browser, like a command line interface, a service, or a daemon.

  • Worker

    An administrator application that can interact with platform APIs. Access to platform APIs is determined by the user's or application's role assignments. The role assignment for a Worker app is set by the assignActorRoles property.

  • Device authorization

    Creating an application of this type initiates an action that returns an activation code to the end user. This enables you to obtain authorization from the end user through (what is typically) a mobile device.

  • Platform applications

    PingOne creates platform applications (PingOne Admin Console, PingOne Application Portal, PingOne Self-Service - MyAccount, and PingFederate-SSO) when the environment is created. The PingFederate-SSO platform application is created only if the PingOne environment includes PingFederate, and unlike the other platform applications, PingFederate-SSO application information is not returned through a GET request.

These are the default grantTypes, response_type, and tokenEndpointAuthMethod attributes for the application types:

Application type Grant type Response type Token endpoint authentication method
Device Authorization DEVICE_CODE, REFRESH_TOKEN N/A NONE
Native AUTHORIZATION_CODE, IMPLICIT TOKEN, ID_TOKEN, CODE NONE
Single-page IMPLICIT TOKEN, ID_TOKEN NONE
Web AUTHORIZATION_CODE CODE CLIENT_SECRET_BASIC
Worker/Non-interactive CLIENT_CREDENTIALS TOKEN CLIENT_SECRET_BASIC

Use Cases

Managing applications

The base endpoint, /environment/{{envID}}/applications, provides endpoint operations to create, read, update, and delete OIDC and SAML application connections. There are POST request examples to show the required properties to create each type of application connection. For more information, see Application Operations.

The secret endpoint, /environments/{{envID}}/applications/{{appID}}/secret, provides endpoint operations to read and update the application's secret, if the requesting actor has a superset of the application's role assignments. For more information, see Application Secret.

Applications support the following additional configuration properties:

  • Application resource grants

    The application resource grants endpoint, /environments/{{envID}}/applications/{{appID}}/grants, provides endpoint operations to create, read, update, and delete the resource grant associated with the application connection. For more information, see Application Resource Grants.

  • Application sign-on policy assignments

    The application sign-on policy assignments endpoint, /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments, provides endpoint operations to create, read, update, and delete the sign-on policies associated with the application connection. For more information, see Application Sign-On Policy Assignments.

  • Application role assignments

    The application role assignments endpoint, /environments/{{envID}}/applications/{{appID}}/roleAssignments, provides endpoint operations to create, read, update, and delete the role assignments associated with the application connection. For more information, see Application Role Assignments.

  • Application attribute mapping

    The application attribute mapping endpoint, /environments/{{envID}}/applications/{{appID}}/roleAssignments, lets you customize the content of an ID token or a SAML assertion by adding custom attributes and their values. For more information, see Application Attribute Mapping.

  • Application MFA push credentials

    Push credentials are required for sending push notifications to a native application. The endpoint, /environments/{{envID}}/applications/{{appID}}/pushCredentials, provides endpoint operations to create, read, update, and delete the push credentials associated with the application connection. This section provides examples for both APNS and FCM push credential types. For more information, see Application MFA Push Credentials.

Application Operations

The Applications service implements operations to create, read, update, and delete, applications resources.

Cross-origin resource sharing

PingOne supports cross-origin resource sharing (CORS), which gives applications running at different domains permission to access resources on PingOne servers. For example, an application at https://myapp.com that uses PingOne to authenticate users needs to request permission to access resources at https://auth.pingone.com before authentication operations are executed. In this case, a request is made to the resource owner (auth.pingone.com) from the requestor (myapp.com) using CORS headers to ask for access privileges. The response from auth.pingone.com returns the CORS Access-Control-Allow-Origin header with a value that confirms the requestor's access rights.

PingOne servers are configured to trust all origins when using access tokens. However, when requesting sensitive resources that use PingOne session cookies for authentication, only specified origins will be trusted. The following endpoints require session cookies for authentication, and only the origins specified in the application’s corsSettings property will be trusted when calling these endpoints:

/{envId}/as/authorize
/{envId}/as/resume
/{envId}/as/signoff
/{envId}/rp/authenticate
/{envId}/rp/callback/{callbackId}
/{envId}/saml20/idp/sso
/{envId}/saml20/idp/startsso
/{envId}/saml20/resume
/{envId}/saml20/idp/slo
/{envId}/wsf/sts/{appId}
/{envId}/wsf/mex/{appId}
/{envId}/wsf/prp/{appId}
/{envId}/wsf/prp/resume

When using session cookies for authentication, no origins will be trusted when calling these endpoints:

/{envId}/as/txs 
/{envId}/saml20/sp/sso
/{envId}/saml20/sp/acs
/{envId}/saml20/sp/jwtacs

Consequently, when defining an application's connection to PingOne, you generally do not need to add your application's domain to a list of trusted origins. Cross-origin requests that use HTTP methods to modify the resource, such as PUT, PATCH, POST, and DELETE, trigger a preflight request to ensure that the initial request can be sent. The browser initiates a preflight HTTP OPTIONS request to verify that the HTTP method used in the actual request is allowed. In these cases, the response from auth.pingone.com to the preflight request returns a response with the CORS Access-Control-Allow-Methods header to specify the allowed methods.

When making CORS requests, only these headers can be used:

  • Accept
  • Accept-Language
  • Content-Language
  • Content-Type
  • Range
  • Authorization
  • Content-Length
  • Cookie
  • Correlation-Id
  • Origin
  • Origin-Cookies
  • Referer or Referrer
  • X-Amz-Date
  • X-Amz-Security-Token
  • X-Api-Key
  • X-client-version
  • X-Content-Type-Options

When accessing CORS responses, you're restricted to reading only the Correlation-Id header (as well as the request body).

Attempting to submit or access headers that are not listed above may prevent you from making CORS requests or reading the responses.

Applications data models

The following applications properties tables show the base data model for properties that apply to all application protocols, and the specific properties for the OpenID Connect (OIDC), SAML, and WS-Federation application protocols.

Applications base data model

Property Type Required? Mutable? Description
accessControl.role.type String Optional Mutable The user role required to access the application. Options are ADMIN_USERS_ONLY. A user is an admin user if the user has one or more of the following roles: Organization Admin, Environment Admin, Identity Data Admin, or Client Application Developer.
accessControl.group.type String Optional Mutable The group type required to access the application. Options are ANY_GROUP (the actor must belong to at least one group listed in the accessControl.group.groups property) and ALL_GROUPS (the actor must belong to all groups listed in the accessControl.group.groups property).
accessControl.group.groups String[] Optional Mutable The group IDs for the groups the actor must belong to for access to the application.
createdAt Date N/A Read-only The time the resource was created.
description String Optional Mutable The description of the application.
enabled String Required Mutable The current enabled state of the application. Options are ENABLED or DISABLED.
environment.id String Required Read-only The PingOne environment associated with the application.
hiddenFromAppPortal Boolean Optional Mutable Whether the application is hidden in the application portal despite the configured group access policy.
homePageUrl String Optional Mutable The custom home page URL for the application.
icon Object Optional Mutable The HREF and the ID for the application icon.
id String Required Read-only The application UUID.
loginPageUrl String Optional Mutable The custom login page URL for the application. If you set the loginPageUrl property for applications in an environment that sets a custom domain, the URL should include the top-level domain and at least one additional domain level. Warning: To avoid issues with third-party cookies in some browsers, a custom domain must be used, giving your PingOne environment the same parent domain as your authentication application. For more information about custom domains, see Custom domains.
name String Required Mutable The name of the application.
protocol String Required Immutable The protocol used by the application. Options are OPENID_CONNECT, SAML, WS-FED, and EXTERNAL_LINK.
type String Required Mutable The application type. Options are WEB_APP, NATIVE_APP, SINGLE_PAGE_APP, SERVICE, CUSTOM_APP, WORKER, PING_ONE_SELF_SERVICE, PING_ONE_ADMIN_CONSOLE, PING_ONE_PORTAL, TEMPLATE_APP, and PORTAL_LINK_APP.
updatedAt Date N/A Read-only The time the resource was last updated.

Applications OIDC settings data model

Property Type Required? Mutable? Description
additionalRefreshTokenReplayProtectionEnabled Boolean Optional Mutable PingOne detects a replay attack when a refresh token is reused outside of its specified grace period (see below for information on refreshTokenRollingGracePeriodDuration). If the refresh token is revoked because of a replay attack, then PingOne also revokes any associated access tokens if, and only if, this setting is enabled. Setting this property to null equates to a false setting. For more information about refresh token rotation, see Refresh token rotation in the PingOne admin guide.
allowWildcardInRedirectUris Boolean Optional Mutable Whether wildcards are allowed in redirect URIs. For more information, see Wildcards in Redirect URIs.
assignActorRoles Boolean Optional Mutable Indicates whether the permissions service should assign to the application the roles of the actor creating the application (defaults to true). This property is set only on the POST request. The property is ignored when included in a PUT request. Best Practice: When creating a Worker app, the best practice is to set this value to false. This is for security purposes, to ensure you assign only the minimal set of permissions necessary for the Worker app.
corsSettings Object Optional Mutable Enables you to customize how the Authorization and Authentication APIs interact with CORS requests that reference the application. If omitted, the application allows CORS requests from any origin except for operations that expose sensitive information (such as, operations from /as/authorize and /as/token). We recommend you use corsSettings, rather than omitting this property.
corsSettings.behavior String Required Mutable Options are "ALLOW_NO_ORIGINS" and "ALLOW_SPECIFIC_ORIGINS". ALLOWS_NO_ORIGINS rejects all CORS requests. ALLOW_SPECIFIC_ORIGINS rejects all CORS requests except those listed in corsSettings.origins.
corsSettings.origins String[] Optional Mutable This must be specified when corsSettings.behavior is ALLOW_SPECIFIC_ORIGINS, and must be omitted or empty when corsSettings.behaviour is ALLOW_NO_ORIGINS. Limited to 20 values. The values are the origins from which CORS requests to the Authorization and Authentication APIs are allowed. Each value is an HTTP or HTTPS URL without a path. The host may be a domain name (including localhost), or an IPv4 address. Subdomains can be specified using the wildcard (*) to match any string.
devicePathId String Optional Mutable A string that specifies a unique identifier within an environment for a device authorization grant flow to provide a short identifier to the application. This property is ignored when the deviceCustomVerificationUri property is configured. The string can contain any letters, numbers, and some special characters (regex: a-zA-Z0-9_-). It can have a length of no more than 50 characters (min/max=1/50).
deviceCustomVerificationUri String Optional Mutable A string that specifies an optional custom verification URI that is returned for the /device_authorization endpoint.
deviceTimeout Integer Required Mutable An integer that specifies the length of time (in seconds) that the userCode and deviceCode returned by the /device_authorization endpoint are valid. This property is required only for applications in which the grantTypes property is set to device_code. The default value is 600 seconds. It can have a value of no more than 3600 seconds (min/max=1/3600).
devicePollingInterval Integer Required Mutable An integer that specifies the frequency (in seconds) for the client to poll the /as/token endpoint. This property is required only for applications in which the grantTypes property is set to device_code. The default value is 5 seconds. It can have a value of no more than 60 seconds (min/max=1/60).
grantTypes String[] Required Mutable The grant type for the authorization request. Options are authorization_code, implicit, refresh_token, device_code, and client_credentials.
idpSignoff Boolean Optional Mutable Set this to true to allow an application to request to terminate a user session using only the ID token. The application is not required to have access to the session token cookie. See GET IdP Signoff for more information.
includeX5t Boolean Optional Mutable Specifies whether tokens signed for this application include the x5t signature header in the signed JWT. See JSON Web Signature (JWS), section "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter.
initiateLoginUri String Optional Mutable The URI to use for third-parties to begin the sign-on process for the application. If specified, PingOne redirects users to this URI to initiate SSO to PingOne. The application is responsible for implementing the relevant OIDC flow when the initiate login URI is requested. This property is required if you want the application to appear in the PingOne Application Portal. See the OIDC specification section Initiating Login from a Third Party for more information.
jwks String Optional Mutable A JWKS string that validates the signature of signed JWTs for applications that use the PRIVATE_KEY_JWT option for the tokenEndpointAuthMethod. This property is required when tokenEndpointAuthMethod is PRIVATE_KEY_JWT and the jwksUrl property is empty. For more information, see Create a private_key_jwt JWKS string. This property is also required if the optional request property JWT on the authorize endpoint is signed using the RS256 (or RS384, RS512) signing algorithm and the jwksUrl property is empty. For more infornmation about signing the request property JWT, see Create a request property JWT.
jwksUrl String Optional Mutable A URL (supports https:// only) that provides access to a JWKS string that validates the signature of signed JWTs for applications that use the PRIVATE_KEY_JWT option for the tokenEndpointAuthMethod. This property is required when tokenEndpointAuthMethod is PRIVATE_KEY_JWT and the jwks property is empty. For more information, see Create a private_key_jwt JWKS string. This property is also required if the optional request property JWT on the authorize endpoint is signed using the RS256 (or RS384, RS512) signing algorithm and the jwks property is empty. For more infornmation about signing the request property JWT, see Create a request property JWT.
kerberos.key Object Optional Mutable A Relationship object containing the certificate issuer (root CA).
kerberos.key.id String Optional Immutable The unique identifier for the Kerberos key. Required if kerberos.key is specified.
mobile.bundleId String Optional Immutable The bundle associated with the application, for push notifications in native apps. The value of the bundleId property is unique per environment, and once defined, is immutable. Used only for applications for the Apple ecosystem.
mobile.huaweiAppId String Optional Immutable The unique identifier for the app on the device and in the Huawei Mobile Service AppGallery. The value of the mobile.huaweiAppId property is unique per environment, and once defined, is immutable. Used only for applications for the Huawei ecosystem.
mobile.huaweiPackageName String Optional Immutable The package name associated with the application, for push notifications in native apps. The value of the mobile.huaweiPackageName property is unique per environment, and once defined, is immutable. Used only for applications for the Huawei ecosystem.
mobile.packageName String Optional Immutable The package name associated with the application, for push notifications in native apps. The value of the mobile.packageName property is unique per environment, and once defined, is immutable. Used only for applications for the Google ecosystem.
mobile.integrityDetection.googlePlay Object Optional Mutable Object that contains the credentials required for using Google's Play Integrity API for integrity detection.
mobile.integrityDetection.googlePlay.verificationType String Optional Mutable The type of verification that should be used. The possible values are GOOGLE and INTERNAL. Using internal verification will not count against your Google API call quota. The value you select for verificationType determines what other parameters you must provide. When set to GOOGLE, you must provide serviceAccountCredentials. When set to INTERNAL, you must provide decryptionKey and verificationKey.
mobile.integrityDetection.googlePlay.serviceAccountCredentials String Optional Mutable Contents of the JSON file that represents your Service Account Credentials. This parameter must be provided if you have set mobile.integrityDetection.googlePlay.verificationType to GOOGLE.
mobile.integrityDetection.googlePlay.decryptionKey String Optional Mutable Play Integrity verdict decryption key from your Google Play Services account. This parameter must be provided if you have set mobile.integrityDetection.googlePlay.verificationType to INTERNAL.
mobile.integrityDetection.googlePlay.verificationKey String Optional Mutable Play Integrity verdict signature verification key from your Google Play Services account. This parameter must be provided if you have set mobile.integrityDetection.googlePlay.verificationType to INTERNAL.
mobile.integrityDetection.mode String Optional Mutable Indicates whether device integrity detection takes place on mobile devices, for the application's enrollment and authentication events. The possible values are ENABLED or DISABLED.
mobile.integrityDetection.excludedPlatforms Array Optional Mutable You can enable device integrity checking separately for Android and iOS by setting mobile.integrityDetection.mode to ENABLED and then using this property to specify an OS where you do not want to use device integrity checking. The possible values are GOOGLE and IOS. Note that this is implemented as an array even though currently you can only include a single value.
mobile.integrityDetection.cacheDuration.amount Integer Optional Mutable The duration between successful integrity detection calls. Every attestation request entails a certain time tradeoff. You can choose to cache successful integrity detection calls for a predefined duration, between a minimum of 1 minute and a maximum of 48 hours. If mobile.integrityDetection.mode is ENABLED, the cache duration must be set.
mobile.integrityDetection.cacheDuration.units String Optional Mutable The time units used for mobile.integrityDetection.cacheDuration.amount. The possible values are MINUTES or HOURS.
mobile.passcodeRefreshDuration.duration Integer Optional Mutable The amount of time a passcode should be displayed before being replaced with a new passcode. Must be between 30 and 60 (seconds).
mobile.passcodeRefreshDuration.timeUnit String Optional Mutable The type of time unit for mobile.passcodeRefreshDuration.duration. Currently, this must be SECONDS.
mobile.push.numberMatching.type String Optional Mutable This option is used to specify the type of number matching that should be used in MFA policies where number matching has been enabled for the application (see the numberMatching.enabled parameter in Device Authentication Policies). The possible values are:
  • SELECT_NUMBER - Users must select the correct number from a group of three numbers
  • ENTER_MANUALLY - Users must enter the number that was shown
    		•
    mobile.uriPrefix String Optional Mutable A URI prefix that enables direct triggering of the mobile application when scanning a QR code. The URI prefix can be set to a universal link with a valid value (which can be a URL address that starts with HTTP:// or HTTPS://, such as https://www.acme.com), or an app schema, which is just a string and requires no special validation.
    parRequirement Enum Optional Mutable Whether pushed authorization requests (PAR) are required. Options are REQUIRED and OPTIONAL. The default value is OPTIONAL.
    parTimeout Integer Optional Mutable PAR timeout in seconds. Must be between 1 and 600. The default value is 60.
    pkceEnforcement String Optional Mutable Specifies how PKCE request parameters are handled on the authorize request. Options are: OPTIONAL: PKCE code_challenge is optional and any code challenge method is acceptable. REQUIRED: PKCE code_challenge is required and any code challenge method is acceptable. S256_REQUIRED: PKCE code_challenge is required and the code_challenge_method must be S256.
    postLogoutRedirectUris String[] Optional Mutable The URLs that the browser can be redirected to after logout.
    redirectUris String[] Optional Mutable The callback URI for the authentication response.
    refreshTokenDuration Integer Optional Mutable The lifetime in seconds of the refresh token. If a value is not provided, the default value is 2592000, or 30 days. Valid values are between 60 and 2147483647. If the refreshTokenRollingDuration property is specified for the application, then this property must be less than or equal to the value of refreshTokenRollingDuration. After this property is set, the value cannot be nullified. This value is used to generate the value for the exp claim when minting a new refresh token.
    refreshTokenRollingDuration Integer Optional Mutable The number of seconds a refresh token can be exchanged before re-authentication is required. If a value is not provided, the refresh token is valid forever. Valid values are between 60 and 2147483647. After this property is set, the value cannot be nullified. This value is used to generate the value for the exp claim when minting a new refresh token.
    refreshTokenRollingGracePeriodDuration Integer Optional Mutable The number of seconds that a refresh token may be reused after having been exchanged for a new set of tokens. This is useful in the case of network errors on the client. Valid values are between 0 and 86400 seconds. Null is treated the same as 0.
    requireSignedRequestObject Boolean Optional Mutable Indicates that the Java Web Token (JWT) for the request query parameter is required to be signed. If false or null (default), a signed request object is not required. Both supportUnsignedRequestObject and this property cannot be set to true.
    responseTypes String[] Optional Mutable The code or token type returned by an authorization request. Options are TOKEN, ID_TOKEN, and CODE. For hybrid flows that specify CODE with TOKEN or ID_TOKEN, see Hybrid grant type.
    signing Object Optional Mutable Configuration for the signing key. If absent, application tokens will be signed and verified by the PingOne default key at runtime. This property only applies to OIDC applications of type WEB_APP, NATIVE_APP, SINGLE_PAGE_APP, and CUSTOM_APP.
    signing.keyRotationPolicy Object Required Mutable Contains the Key Rotation Policy (KRP) ID. This property is required if signing is set.
    signing.keyRotationPolicy.id String Required Mutable Reference to a KRP ID from certificate management. This property is required if signing is set.
    supportUnsignedRequestObject Boolean Optional Mutable Indicates whether the Java Web Token (JWT) for the request query parameter is allowed to be unsigned. If false or null (default), an unsigned request object is not allowed. Both requireSignedRequestObject and this property cannot be set to true.
    tags String[] Optional Mutable An array that specifies the list of labels associated with the application. Options are PING_FED_CONNECTION_INTEGRATION. Only applicable for Create Application (OIDC Protocol - PingFederate Worker App).
    targetLinkUri String Optional Mutable The URI for the application. If specified, PingOne will redirect application users to this URI after a user is authenticated. In the PingOne admin console, this becomes the value of the target_link_uri parameter used for the Initiate Single Sign-On URL field.
    template Object Optional Mutable Valid only when the application type is TEMPLATE_APP. This identifies the application as integration in Integration Catalog. (by integration.id and version.id) and provides key-value map of parameters needed by the integration
    template.configuration Object Required Mutable Contains a key/value map of the parameters required by the integration in Integration Catalog.
    template.integration.id String Required Mutable The UUID of the integration in Integration Catalog.
    template.version.id String Required Mutable The UUID of the integration version in Integration Catalog.
    tokenEndpointAuthMethod String Optional Mutable The client authentication methods supported by the token endpoint. Options are NONE, CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, PRIVATE_KEY_JWT, and CLIENT_SECRET_JWT.
    Applications OIDC settings data model for PING_ONE_SELF_SERVICE

    For applications of type PING_ONE_SELF_SERVICE only. Ignored for all other application types.

    Property Type Required? Mutable? Description
    applyDefaultTheme Boolean Required Mutable If true, applies the default theme to the self service application.
    enableDefaultThemeFooter Boolean Required Mutable If true, shows the default theme footer on the self service application. Applies only if applyDefaultTheme is also true.
    manageDevicesViaMyAccountEnabled Boolean Optional Mutable When set to true, PingID users can manage their devices using the MyAccount app. This will also add the MyAccount app to all PingID policies that already include Device Management. To limit the scope of PingID users, ensure an MFA policy or MFA DaVinci flow policy limiting their scope is added to the MyAccount app. For more information, see Self service in the PingOne admin documentation.
    Applications OIDC settings data model for PING_ONE_PORTAL

    For applications of type PING_ONE_PORTAL only. Ignored for all other application types.

    Property Type Required? Mutable? Description
    applyDefaultTheme Boolean Required Mutable If true, applies the default theme to the app portal application.

    Applications SAML settings data model

    Property Type Required? Mutable? Description
    acsUrls String[] Required Mutable The Assertion Consumer Service URLs. The first URL in the list is used as default (there must be at least one URL).
    assertionDuration Integer Required Mutable The assertion validity duration in seconds.
    assertionSigned Boolean Optional Mutable Indicates whether the SAML assertion itself should be signed. The default value is true.
    corsSettings Object Optional Mutable Enables you to customize how the Authorization and Authentication APIs interact with CORS requests that reference the application. If omitted, the application allows CORS requests from any origin except for operations that expose sensitive information (such as, operations from /as/authorize and /as/token). We recommend you use corsSettings, rather than omitting this property.
    corsSettings.behavior String Required Mutable Options are "ALLOW_NO_ORIGINS" and "ALLOW_SPECIFIC_ORIGINS". ALLOWS_NO_ORIGINS rejects all CORS requests. ALLOW_SPECIFIC_ORIGINS rejects all CORS requests except those listed in corsSettings.origins.
    corsSettings.origins String[] Optional Mutable This must be specified when corsSettings.behavior is ALLOW_SPECIFIC_ORIGINS, and must be omitted or empty when corsSettings.behaviour is ALLOW_NO_ORIGINS. Limited to 20 values. The values are the origins from which CORS requests to the Authorization and Authentication APIs are allowed. Each value is an HTTP or HTTPS URL without a path. The host may be a domain name (including localhost), or an IPv4 address. Subdomains can be specified using the wildcard (*) to match any string.
    defaultTargetUrl String Optional Mutable This is used as the RelayState parameter by the IdP to deep link into the application after authentication. This value can be overridden by the applicationUrl query parameter for GET Identity Provider Initiated SSO. Although both of these parameters are generally URLs, because they are used as deep links, this is not enforced. If neither defaultTargetUrl nor applicationUrl is specified during a SAML authentication flow, no RelayState value is supplied to the application. The defaultTargetUrl (or the applicationUrl) value is passed to the SAML application’s ACS URL as a separate RelayState key value (not within the SAMLResponse key value).
    enableRequestedAuthnContext Boolean Optional Mutable Indicates whether requestedAuthnContext is taken into account in policy decision-making.
    idpSigning.algorithm String Optional Mutable The algorithm used by the IdP signing key. Algorithms supported: SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withECDSA, SHA384withECDSA, and SHA512withECDSA.
    idpSigning.key.id String Optional Mutable The certificate to be used by the identity provider to sign assertions and responses. If this property is omitted, the default signing certificate for the environment is used.
    nameIdFormat String Optional Mutable The format of the Subject NameID attribute in the SAML assertion. Options are
    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: The Subject's NameID format is not specified. Use this format if you are not sure which format to use.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: The Subject's NameID format is in the form of an email address.
    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: The Subject's NameID format is an opaque unique identifier for a user that retains the same value over time.
    • urn:oasis:names:tc:SAML:2.0:nameid-format:transient: The Subject's NameID format is a randomly generated identifier. A different value is used for each SSO for a given user.
    responseSigned Boolean Optional Mutable Indicates whether the SAML assertion response itself should be signed. The default value is False.
    sessionNotOnOrAfterDuration Integer Optional Mutable Update this value if the SAML application requires a different SessionNotOnOrAfter attribute value within the AuthnStatement element than the NotOnOrAfter value set by the assertionDuration property.
    sloBinding String Optional Mutable The binding protocol to be used for the logout response. Options are HTTP_REDIRECT or HTTP_POST. The default is HTTP_POST; existing configurations with no data default to HTTP_POST. This is an optional property.
    sloEndpoint String Optional Mutable The logout endpoint URL. This is an optional property. However, if a sloEndpoint logout endpoint URL is not defined, logout actions result in an error.
    sloResponseEndpoint String Optional Mutable The endpoint URL to submit the logout response. If a value is not provided, the sloEndpoint property value is used to submit SLO response.
    sloWindow Integer Optional Mutable Defines how long PingOne can exchange logout messages with the application, specifically a LogoutRequest from the application, since the initial request. PingOne can also send a LogoutRequest to the application when a single logout is initiated by the user from other session participants, such as an application or identity provider. This setting is per application. The SLO logout is separate from the user session logout that revokes all tokens.
    spEncryption Object Optional Mutable Enables PingOne to encrypt SAML assertions to be sent to the application. Assertions are not encrypted by default.
    spEncryption.algorithm String Required Mutable The algorithm for encrypting the assertions (AES_128, AES_256, or TRIPLEDES).
    spEncryption.certificate Object Required Mutable Contains the ID of the encryption public certificate that has been uploaded to PingOne.
    spEncryption.certificate.id String Required Mutable The unique identifier of the encryption public certificate that has been uploaded to PingOne.
    spEntityId String Required Immutable The service provider entity ID used to lookup the application. This must be unique within the environment.
    spVerification.authnRequestSigned Boolean Optional Mutable Whether the Authn Request signing should be enforced. Default is false.
    spVerification.certificates[].id String[] Optional Mutable An array that specifies the certificate IDs used to verify the service provider signature.
    template Object Optional Mutable Valid only when the application type is TEMPLATE_APP. This identifies the application as integration in Integration Catalog.
    template.configuration Object Required Mutable Contains a key/value map of the parameters required by the integration in Integration Catalog.
    template.integration.id String Required Mutable The UUID of the integration in Integration Catalog.
    template.version.id String Required Mutable The UUID of the integration version in Integration Catalog.
    Applications SAML metadata settings data model
    Property Type Required? Mutable? Description
    acsBindings String Optional Mutable The assertion consumer service binding protocol. Options are: HTTP_REDIRECT or HTTP_POST
    acsUrls String[] Optional Mutable The assertion consumer service URLs.
    authnRequestsSigned Boolean Optional Mutable Indicates whether the SAML authentication request is signed.
    encryptionCertificate.pkcs7Der Byte[] Optional Mutable The PKCS7 encryption certificate in DER format.
    sloBinding String Optional Mutable The SAML single logout binding protocol used for logout response. Options are: HTTP_REDIRECT or HTTP_POST.
    sloEndpoint String Required Mutable The SAML single logout endpoint URL.
    signingCertificates[].pkcs7Der Byte[] Optional Mutable The PKCS7 signing certificates in DER format.

    Applications WS-Federation settings data model

    Property Type Required? Mutable? Description
    audienceRestriction String Optional Mutable The service provider ID. Defaults to urn:federation:MicrosoftOnline.
    corsSettings Object Optional Mutable Enables you to customize how the Authorization and Authentication APIs interact with CORS requests that reference the application. If omitted, the application allows CORS requests from any origin except for operations that expose sensitive information (such as, operations from /as/authorize and /as/token). We recommend you use corsSettings, rather than omitting this property.
    corsSettings.behavior String Required Mutable Options are "ALLOW_NO_ORIGINS" and "ALLOW_SPECIFIC_ORIGINS". ALLOWS_NO_ORIGINS rejects all CORS requests. ALLOW_SPECIFIC_ORIGINS rejects all CORS requests except those listed in corsSettings.origins.
    corsSettings.origins String[] Optional Mutable This must be specified when corsSettings.behavior is ALLOW_SPECIFIC_ORIGINS, and must be omitted or empty when corsSettings.behaviour is ALLOW_NO_ORIGINS. Limited to 20 values. The values are the origins from which CORS requests to the Authorization and Authentication APIs are allowed. Each value is an HTTP or HTTPS URL without a path. The host may be a domain name (including localhost), or an IPv4 address. Subdomains can be specified using the wildcard (*) to match any string.
    domainName String Required Mutable The federated domain name (for example, the Azure custom domain).
    idpSigning Object Required Mutable Contains the information about the signing of requests by the identity provider (IdP).
    idpSigning.algorithm String Required Mutable The signature algorithm to be used for signing. Algorithms supported: SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withECDSA, SHA384withECDSA, and SHA512withECDSA.
    idpSigning.key String Required Mutable The key pair to be used by the IdP to sign requests. If this isn't specified, the default signing certificate for the environment is used.
    idpSigning.key.id String Required Mutable The ID of the key specified for idpSigning.key.
    kerberos Object Optional Mutable Contains the Kerberos authentication settings. Set this to null to disable Kerberos authentication.
    kerberos.gateways Object[] Optional Mutable Contains the gateway properties.
    kerberos.gateways.id String Required Mutable The UUID of the LDAP gateway.
    kerberos.gateways.type String Required Mutable The gateway type. This must be "LDAP".
    kerberos.gateways.userType.id String Required Mutable The UUID of a user type in the list of userTypes for the LDAP gateway.
    replyUrl String Required Mutable The URL that the replying party (such as, Office365) uses to accept submissions of RequestSecurityTokenResponse messages that are a result of SSO requests.
    sloEndpoint String Optional Mutable The single logout endpoint URL.
    subjectNameIdentifierFormat String Optional Mutable The format to use for the SubjectNameIdentifier element. This value must be one of the following:
    urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    applications APPLICATION.CREATED
    applications APPLICATION.UPDATED
    applications APPLICATION.DELETED

    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, or your license is exceeded.
    404 The requested resource was not found.
    500 An unexpected error occurred.

    Create Application (OIDC Protocol - Web App)

    Create Application (OIDC Protocol - Native App)

    Create Application (OIDC Protocol - Single Page App)

    Create Application (OIDC Protocol - Service App)

    Create Application (OIDC Protocol - Worker App)

    Create Application (OIDC Protocol - Worker Interactive App)

    Create Application (OIDC Protocol - PingFederate Worker App)

    Create Application (OIDC Device Authorization Grant)

    Create Application (OIDC Mobile App)

    Create Application (SAML Protocol)

    Create Application (WS-Federation Protocol)

    Read All Applications

    Read One Application

    Update Application (OIDC)

    Update Application (SAML)

    Update Application (WS-Federation)

    Delete Application

    Application Attribute Mapping

    ID token and SAML assertion customization

    The application attributes service lets you customize the content of an ID token or a SAML assertion by adding custom attributes and their values. Custom attributes have a cumulative length constraint of 16 Kb. See Custom attributes in Schemas for more information.

    In the Authorization request header field of all samples, the accessToken value is your full base64url-encoded JSON web token generated by the authentication service.

    OpenID Connect application attribute mappings

    For OpenID Connect (OIDC) applications, the user claim defined by the custom attribute mapping is returned in the ID token, regardless of the scopes specified in the authorization request. For example, suppose you want to include a user's accountId in ID tokens associated with the specified OIDC application, a custom application attribute resource can be created to map the user's account ID to the accountId PingOne user attribute. The request looks like this:

    curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer {{accessToken}}' \
-d '{
	"name": "userAccountID",
	"value": "${user.accountId}",
	"required": true
}'

    SAML application attribute mappings

    For SAML applications, the user claim defined by the custom attribute mapping is returned in the SAML assertion.

    For example, suppose you want to include an externalId in assertions associated with the specified SAML application, a custom application attribute resource can be created to map the SAML externalId attribute to the user's external ID attribute. The request looks like this:

    curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer {{accessToken}}' \
-d '{
	"name": "externalId",
	"value": "${user.externalId}",
	"required": true
}'

    Advanced attribute mapping

    You can use PingOne's expression language for advanced attribute mapping. The supported expression language is an augmentation of SpEL. SpEL is a powerful expression language used for querying and manipulating an object graph at runtime.

    For example, with advanced attribute mapping capabilities, you can write an expression that concatenates two or more user attributes in the value property:

    curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer {{accessToken}}' \
-d '{
	"name": "fullName",
	"value": "${user.name.given + ', ' + user.name.family}",
	"required": true
}'

    In this request, the fullName mapped attribute includes the user's first name and last name in the response.

    Applications attribute mapping data model

    Property Type Required? Mutable? Description
    application.id String Required Read-only The application associated with the application mapping resource.
    createdAt Date N/A Read-only The time the resource was created.
    environment.id String Required Read-only The environment associated with the application mapping resource.
    id UUID Required Read-only The application mapping ID.
    mappingType String Optional Mutable The mapping type of the attribute. Options are CORE, SCOPE, and CUSTOM. The CORE and SCOPE mapping types are for reserved attributes managed by the API and cannot be removed. Attribute values for these mapping types can be updated. The CUSTOM mapping type is for user-defined attributes. Attributes of this type can be updated and deleted.
    name String Required Immutable The name of attribute. Must be unique within an application. The property is set on create only and cannot be changed after creation. For SAML applications, the samlAssertion.subject name is a reserved case-insensitive name which indicates the mapping to be used for the subject in an assertion. For OpenID Connect applications, the following names are reserved and cannot be used:
    • acr
    • amr
    • at_hash
    • aud
    • auth_time
    • azp
    • client_id
    • exp
    • iat
    • iss
    • jti
    • nbf
    • nonce
    • org
    • scope
    • sid
    • sub
    nameFormat String Optional Mutable A URI reference representing the classification of the attribute. Helps the service provider interpret the attribute format.
    required Boolean Required Mutable Whether a mapping value is required for this attribute. If true, a value must be set and a non-empty value must be available in the SAML assertion or ID token.
    updatedAt Date N/A Read-only The time the resource was updated.
    value String Required Mutable The string constants or expression for mapping the attribute path against a specific source. The expression format is: ${<source>.<attribute_path>}. The only supported source is user (for example, ${user.id}).
    idToken Boolean Optional Mutable Whether the attribute mapping should be available in the ID Token. This property is applicable only when the application's protocol property is OPENID_CONNECT. If omitted, the default is true. Note that the idToken and userInfo properties cannot both be set to false. At least one of these properties must have a value of true.
    userInfo Boolean Optional Mutable Whether the attribute mapping should be available through the /as/userinfo endpoint. This property is applicable only when the application's protocol property is OPENID_CONNECT. If omitted, the default is true. Note that the idToken and userInfo properties cannot both be set to false. At least one of these properties must have a value of true.
    oidcScopes List Optional Mutable OIDC resource scope IDs that this attribute mapping is available for exclusively. This setting overrides any global OIDC resource scopes that contain an attribute mapping with the same name. The list can contain only scope IDs that have been granted for the application through the /grants endpoint. A null value is accepted for backwards compatibility. However, an empty set is invalid, and one scope ID is expected. If null, the response includes this mapping in the openid scope.

    OIDC application core mapping attributes

    Property Type Required? Mutable? Description
    sub String Required Mutable A string that specifies the core OIDC application mapping attribute. The default user attribute value is ${user.id} and the required property value must be set to true.

    SAML application core mapping attributes

    Property Type Required? Mutable? Description
    saml_subject String Required Mutable A string that specifies the core SAML mapping attribute. The default user attribute value is ${user.id} and the required property value must be set to true.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    applications ATTRIBUTE.CREATED
    applications ATTRIBUTE.UPDATED
    applications ATTRIBUTE.DELETED

    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.
    500 An unexpected error occurred.

    Create Application Attribute Mapping

    Read All Application Attribute Mappings

    Read One Application Attribute Mapping

    Update Application Attribute Mapping

    Delete Application Attribute Mapping

    Application Flow Policy Assignments

    Flow policy assignment endpoints manage the flow policies associated with the specified application. An application can have zero or more flow policies assigned to it that determine how users are authenticated. The number of flow policies assigned to an application also controls how the authentication flow progresses.

    No flow policy assignments

    Applications that have no flow policy assignments use the environment resource's default sign-on policy to authenticate users (or a designated sign-on policy assignment).

    One flow policy assignment

    Applications that have one flow policy assignment always use that flow policy to authenticate users.

    Two or more flow policy assignments

    If an application has two or more assigned flow policies, the authentication flow uses the flow policy with the highest priority (priority 1) first. If authentication is successful, the flow is complete. If authentication fails, the flow initiates the flow policy with the next highest priority. The flow continues until one of the assigned flow policies completes successfully or all policies have been tried and failed.

    OIDC applications can request a lower-priority policy by using the acr_values OIDC parameter with the desired PingOne authentication name or DaVinci flow policy ID. See OpenID Connect/OAuth2 data model.

    SAML applications can request a lower-priority policy by sending a SAML 2.0 authentication request with the RequestedAuthnContext parameter, where the value indicates the desired PingOne authentication name or DaVinci flow policy ID. Note that the enableRequestAuthnContext must be set to true for the SAML application. See SAML settings data model.

    Flow policies and the PingOne application portal

    If the PingOne application portal is not configured with any flow policies, it will use the default PingOne policy.

    You can apply policies other than the default to the PingOne application portal by appending the policy query parameter to your Application Portal Home Page URL. For example, the Home Page URL https://apps.pingone.com/<envID>/myapps/ would become https://apps.pingone.com/<envID>/myapps/?policy=<value>, where <value> is the name of a configured PingOne policy, or the ID of a configured DaVinci flow policy. If the policy name or ID doesn't match any configured policy, then PingOne returns an error.

    Application flow policy assignments data model

    Property Type Required? Mutable? Description
    application.id String Required Read only A string that specifies the application resource ID associated with the flow policy assignment.
    environment.id String Required Read only A string that specifies the environment associated with the application.
    flowPolicy.id String Required Mutable A string that specifies the flow policy resource ID associated with the flow policy assignment.
    id String Required Read only A string that specifies the flow policy assignment resource's unique identifier.
    priority Integer Required Mutable The order in which the policy referenced by this assignment is evaluated during an authentication flow relative to other policies. An assignment with a lower priority will be evaluated first.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    applications FLOW_POLICY_ASSIGNMENT.CREATED
    applications FLOW_POLICY_ASSIGNMENT.UPDATED
    applications FLOW_POLICY_ASSIGNMENT.DELETED

    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.
    500 An unexpected error occurred.

    Create an Application Flow Policy Assignment

    Read All Application Flow Policy Assignments

    Read One Application Flow Policy Assignment

    Update an Application Flow Policy Assignment

    Delete an Application Flow Policy Assignment

    Application MFA Push Credentials

    Push credentials are required for the purpose of sending push notifications to a native application. Push credentials must be defined for the application.

    The push credentials endpoint implements functions to create, read, update and delete the push credentials associated with native application resources.

    There are three types of push credentials:

    • APNS (Apple)
    • FCM_HTTP_V1 (Google)
    • HMS (Huawei)

    The FCM type, used previously for Google Play-based applications, has been deprecated. Use FCM_HTTP_V1 instead.

    MFA push credentials data model

    Property Type Required? Mutable? Description
    type String Required Immutable Specifies the push credential type.
    Valid values:
    • APNS (for Apple)
    • FCM_HTTP_V1 (for Google)
    • HMS (for Huawei)
    • FCM (deprecated, used previously for Google)
    clientId String Required Immutable Used only if type is set to HMS. OAuth 2.0 Client ID from the Huawei Developers API console.
    clientSecret String Required Immutable Used only if type is set to HMS. The client secret associated with the OAuth 2.0 Client ID.
    googleServiceAccountCredentials String Required Immutable Used when type is set to FCM_HTTP_V1. The value should be the contents of the JSON file that represents your Service Account Credentials.
    key String Required Immutable Used when type is set to APNS. The value should be the key ID. Before the deprecation of the FCM type, this was also used for the server key.
    teamId String Required Immutable Used only if type is set to APNS. Used to identify teams.
    token String Required Immutable Used only if type is set to APNS. Used as the authentication token signing key to securely connect to APNS. This is a p8 file with a private key format.

    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.
    500 Unexpected server error.

    Create MFA Push Credential (APNS)

    Create MFA Push Credential (FCM_HTTP_V1)

    Create MFA Push Credential (HMS)

    Read All MFA Push Credentials

    Read One MFA Push Credential

    Update MFA Push Credential

    Delete MFA Push Credential

    Application Resource Grants

    Resources are the protected endpoints that applications request access to using OAuth 2 authorization services. A resource access grant specifies the identifier of the resource associated with the specified application.

    Applications resource grant data model

    Property Type Required? Mutable? Description
    application.id String N/A Read-only The application resource ID associated with the resource grant.
    createdAt Date N/A Read-only The time the resource was created.
    id String N/A Read-only The application resource grant ID.
    resource.id String N/A Read-only The ID of the protected resource associated with this grant.
    scopes.id String[] Required Mutable The IDs of the scopes associated with this grant.
    updatedAt Date N/A Read only The time the resource was last updated.

    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.
    500 An unexpected error occurred.

    Create Grant

    Read All Grants for an Application

    Read One Grant for an Application

    Update Grant

    Delete Grant

    Application Role Assignments

    The role assignments endpoint implements functions to create, read, and delete the role assignments associated with applications resources. For more information about roles and the permissions associated with each role, see Roles.

    Role assignments are defined by the role itself, and at a more granular level by the scope attribute associated with the role assignment. The role assignment scope identifies the type of platform resource that defines the scope, and the id of the specific resource to which the scope applies. The following sample shows the scope attribute, which includes the resource type and id attributes. In this case, the scope is restricted to the environment resource identified by its id.

    {
  "scope": {
   "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
   "type": "ENVIRONMENT"
   }
}

    Role assignment scopes can be:

    • Organization

    • Environment

    • Population

    • Application

    Applications role assignments data model

    Property Type Required? Mutable? Description
    application.id String Required Read only The application resource ID associated with the role assignment.
    environment.id String Required Read only The environment associated with the application role assignment.
    id String Required Read only The application role assignment ID.
    readOnly Boolean Optional Mutable Indicates whether this role assignment can be deleted by the current actor.
    role.id String Required Mutable The role ID.
    scope.id String Required Mutable The role assignment scope ID. When this is an application ID, because an application ID is guarenteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.
    scope.type String Required Mutable The type of resource defining the scope of the Role assignment. Options are ORGANIZATION, ENVIRONMENT, and POPULATION, APPLICATION.

    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.
    404 The requested resource was not found.

    Create Application Role Assignments

    Read Application Role Assignments

    Read One Application Role Assignment

    Delete Application Role Assignment

    Application Secret

    The client secret endpoint is available to users or worker applications only if they have a superset of the application's role assignments.

    Access to the application's client secret is restricted based on the accessing user's or application's role assignments. For example, if a client has the Environment Admin role, an actor with an Identity Admin role cannot see the client secret. This restriction addresses privilege escalation issues by preventing the Identity Admin user from doing things with the client that the Identity Admin role assignment does not allow. You need the Client Application Developer role to perform operations on application resources.

    Best practices

    • Do not store an application secret in applications that are publicly available.

    • For security purposes, regenerate application secrets regularly.

    • If you suspect an application secret has been compromised, generate a new application secret immediately.

    Applications secret data model

    Property Type Required? Mutable? Description
    environment.id String Read-only The environment associated with the application.
    previous Object Optional Read only An object that specifies the previous secret, when it expires, and when it was last used.
    previous.secret String N/A Read only A string that specifies the previous application secret. This property is returned in the response if the previous secret is not expired.
    previous.expiresAt Timestamp Optional Read only A timestamp that specifies how long this secret is saved (and can be used) before it expires. Supported time range is 1 minute to 30 days.
    previous.lastUsed Timestamp Optional Read only A timestamp that specifies when the previous secret was last used.
    secret String Required Read-only The application secret ID used to authenticate to the authorization server. The secret has a minimum length of 64 characters per SHA-512 requirements when using the HS512 algorithm to sign ID tokens using the secret as the key.

    Response codes

    Code Message
    200 Successful operation.
    201 Successfully created.
    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.
    500 An unexpected error occurred.

    Update Application Secret

    Read Application Secret

    Delete Previous Application Secret

    Application Sign-On Policy Assignments

    Sign-on policy assignment endpoints manage the sign-on policies associated with the specified application. An application can have zero or more sign-on policies assigned to it that determine how users are authenticated. The number of sign-on policies assigned to an application also controls how the authentication flow progresses.

    No sign-on policy assignments

    Applications that have no sign-on policy assignments use the environment resource's default sign-on policy to authenticate users. Every environment has one designated sign-on policy as its default policy. If the environment's default sign-on policy changes, then the application's sign-on policy changes to use the updated default policy.

    One sign-on policy assignment

    Applications that have one sign-on policy assignment always use that sign-on policy to authenticate users. For example, if the application has the Single_Factor sign-on policy assigned, the application will always use this basic authentication method that prompts users to enter a username and password to authenticate the account.

    Two or more sign-on policy assignments

    If an application has two or more assigned sign-on policies, the authentication flow uses the sign-on policy with the highest priority (priority 1) first. If authentication is successful, the sign-on flow is complete. If authentication fails, the flow initiates the sign-on policy with the next highest priority. If authentication fails again, the sign-on flow initiates the next sign-on policy. The sign-on flow continues until one of the assigned sign-on policies completes successfully or all policies have been tried and failed.

    Sign-on policy priority when acr_values is set

    For applications with the protocol property set to OPENID_CONNECT, the acr_values property (set on the authorize request) identifies the exact list of sign-on policies that can execute at sign on. At sign-on, only the sign-on policies listed in the acr_values property are evaluated, and they are evaluated based on the order of the policies listed in this property. In addition, if there are numerous sign-on policies assigned to an application, setting the acr_values property limits the number of sign-on policies evaluated to only those listed in this property.

    For example, if the authorize request includes acr_values=Multi_Factor Single_Factor, the authentication flow executes the Multi_Factor policy first. If the multi-factor sign-on flow completes all conditions for the policy, the flow completes and the user is issued a token. If the multi-factor policy fails, the Single_Factor policy executes. If that policy completes all conditions, the flow completes and the user is issued a token. If the single-factor policy is the last policy in the acr_values list, and it fails, then the sign-on flow fails. No other sign-on policies are tried, even if the application has additional sign-on policy assignments.

    Applications sign-on policy assignments data model

    Property Type Required? Mutable? Description
    application.id String Required Read-only The application resource ID associated with the sign-on policy assignment.
    environment.id String Required Read-only The environment associated with the application sign-on policy assignment.
    id String Required Read-only The sign-on policy assignment resource’s unique identifier.
    priority Integer Required Mutable The order in which the policy referenced by this assignment is evaluated during an authentication flow relative to other policies. An assignment with a lower priority will be evaluated first.
    signOnPolicy.id String Required Mutable The sign-on policy resource's unique identifier associated with this sign-on policy assignment.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    applications SIGN_ON_POLICY_ASSIGNMENT.CREATED
    applications SIGN_ON_POLICY_ASSIGNMENT.UPDATED
    applications SIGN_ON_POLICY_ASSIGNMENT.DELETED

    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.
    500 An unexpected error occurred.

    Create SOP Assignment

    Read All SOP Assignments

    Read One SOP Assignment

    Update SOP Assignment

    Delete SOP Assignment

    Integration Catalog

    Use the endpoints in the Integration Catalog to discover and retrieve integration metadata, SAML metadata, and download integration kits as a compressed file.

    Integration data model

    Property Type Required? Mutable? Description
    categories String[] Optional Mutable The list of categories used to classify the integration. Valid strings include alphanumeric characters, underscore, hyphen, and space.
    createdAt Date Required Immutable Creation date of the integration.
    description String Optional Mutable The description of the integration in HTML to be used for the integration listing. You can use class and style attributes for inline styling. There's a 4000 character limit for the description.
    id String Required Immutable The platform-generated ID of this integration.
    logo String Optional Mutable A logo to use for the integration. If specified, the associated properties are required.
    logo.href String Required Mutable The href to the absolute URL of the image.
    logo.id String Required Mutable The image ID generated by the Image service.
    marketingLandingPageUrl String Optional Mutable Absolute URL link to the marketing landing page.
    name String Required Mutable Name of the integration.
    pingProductNames String[] Required Mutable The Ping product associated with the integration. Can include: PINGID, PINGONE_ENTERPRISE, PINGONE, PINGACCESS, PINGFEDERATE, PINGDIRECTORY, PINGDATAGOVERNANCE, orPINGINTELLIGENCE_FOR_APIS, PINGONE_ADVANCED_SERVICES
    publisher String Required Mutable Name of the publisher.
    tags String[] Optional Mutable Tags to apply to the integration metadata. Can include: SSO, AUTHENTICATION, MFA, INTELLIGENCE, GOVERNANCE, IDAAS, ACCESS, DIRECTORY, or PROVISIONING.
    thirdParty Object Optional Mutable Metadata that defines the third party related to this integration.
    thirdParty.companyName String Required Mutable Name of the third party company for the listing.
    thirdParty.products String[] Optional Mutable Names of the third party products for the integration.

    Integration version data model

    Each integration can have versions. Valid integration version numbers match the regular expression (^\d+.\d+(.\d+)?$). So, 1.0.2 and 2.06 are valid versions. Examples of invalid versions include v.1.2 and 1.2.3.4.

    Property Type Required? Mutable? Description
    configuration Object Optional Mutable The configuration of the integration version. If specified, configuration.schema and configuration.properties is required.
    configuration.schema Object Required Mutable Contains a JSON schema defining the integration version.
    configuration.properties Object Required Mutable Contains the property names and assigned values for the integration version.
    description String Optional Mutable Unicode characters. The description of this integration metadata version.
    id String Required Immutable The platform-generated ID of this integration metadata version.
    integration Object Required Read only The parent integration of the integration version.
    integration.id String Required Immutable The platform-generated ID of the parent integration.
    name String Required Mutable A unique name for the integration metadata version.
    number String Required Mutable A unique number for the integration version.
    type String Optional Mutable The type of integration for this version. Currently, the only valid values are PRODUCT_INTEGRATION_KIT and SAML.

    Integration Kit data model (extends Integration Version)

    Integration version metadata with a type of PRODUCT_INTEGRATION_KIT will include this data.

    Property Type Required? Mutable? Description
    documentationUrl String Optional Mutable Absolute URL to the documentation.
    endOfLifeOn Date Optional Mutable EOL support date in the form yyyy-mm-dd.
    integratedWith Object Optional Mutable Ping product integration details.
    integratedWith.name String Required Mutable Name of the compatible Ping product with which this version integrates. Can include: PINGID, PINGONE_ENTERPRISE, PINGONE, PINGACCESS, PINGFEDERATE, PINGDIRECTORY, or PINGDATAGOVERNANCE
    integratedWith.minVersion String Optional Mutable Earliest version of the integrated Ping product.
    integratedWith.maxVersion String Optional Mutable Latest version of the integrated Ping product.
    number String Required Mutable Unique number for the integration version.
    releasedOn Date Required Mutable Release date in the form yyyy-mm-dd.

    SAML data model (extends Integration Version)

    Integration version metadata with a type of SAML will include the following data.

    Property Type Required? Mutable? Description
    assertionConsumerService String Required Mutable The URL to which PingOne sends SAML responses. Parameterize the URL using ${_paremter_}. For example, https://${subdomain}.slack.com. The maximum length is 2000 characters.
    assertionEncrypted Boolean Optional Mutable The state of assertion encryption. True if encrypted.
    defaultTarget String Optional Mutable After an IdP-initiated SSO, this URL is passed in the RelayState value in the SAML response. Informs the IdP where to send its response. Parameterize the URL using ${_paremter_}. For example, https://${subdomain}.slack.com.
    entityId String Optional Mutable Unique ID for the application.
    nameIdFormat String Optional Mutable This can be one of the following:
    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

    • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
    protocolVersion String Required Mutable The SAML protocol version supported: 2.0, 1.1, or 1.0.
    slo Object Optional Mutable The Single Logout information.
    slo.requestEndpoint String Optional Mutable The endpoint where SLO requests are sent.
    slo.responseEndpoint String Optional Mutable The endpoint where SLO responses are sent.
    slo.binding String Optional Mutable The SLO binding. Must be either HTTP_POST or HTTP_REDIRECT
    thirdParty Object Optional Mutable Third-party IdP information.
    thirdParty.metadata Object Optional Mutable The third-party IdP metadata.
    thirdParty.metadata.href String Optional Mutable URL of IdP's SAML metadata XML.
    thirdParty.instructions.href String Optional Mutable URL of IdP's setup instructions.

    Attribute data model

    Only available for SAML integration metadata. The attribute data is used to store any attributes that are predefined by providers.

    Property Type Required? Mutable? Description
    id String Required Mutable Auto-generated ID of this attribute.
    integration Object Required Read only The parent integration of the integration version.
    integration.id String Required Immutable The platform-generated ID of the parent integration.
    name String Optional Mutable Attribute name the application expects. Unique within the integration version and in the form urn:oasis:names:tc:SAML:2.0:attrname-format:uri.
    required Boolean Optional Mutable Whether or not the attribute is required. If true, the value property must be set with a non-empty value. Default is false.
    schema String Required Mutable A JSON schema describing the current attribute mapping.
    version Object Required Read only The relationship to the parent integration version.
    version.id String Required Immutable The platform-generated ID of the parent integration version.

    Use Cases

    Read All Integration Metadata

    Read All Integration Versions Metadata

    Read All Attributes of an Integration Version (SAML only)

    Read One Integration Metadata

    Read One Integration Version Metadata

    Read One Attribute of an Integration Version (SAML only)

    Download One Integration Version Asset

    Environment Management

    Environments define separate working domains within an organization. Environments are used to model regions within a large global enterprise such as NA (North America) or EU (European Union). They are also used as the defining entity to segregate enterprise operations by functionality, staging environments, or configurations.

    In the management API sample requests shown in this document, the {{apiPath}} variable in the sample requests represents the regional domain for the PingOne server. See PingOne API domains for more information.

    For more information, see Environments.

    Environments contain many of the core resources on which all identity services are built. Environments encompass:

    • MFA

      A multi-factor authentication (MFA) authentication policy prompts users to complete an MFA action, such as entering a one-time passcode received on a registered device or accepting a push confirmation on a registered native device. There ae severl services that enable MFA configuration at the environment level.

      For more information, see Device Authentication Policies, MFA Settings, and Sign-On Policies.

    • Populations

      In PingOne, a population defines a set of users, similar to an organizational unit (OU). In a given environment, you can use populations to simplify the management of users. For example, you can create a population for similar types of users and apply a password policy to that population. You must create at least one population before you can create users. An individual user cannot belong to more than one population simultaneously, but users can be moved to a different populations.

      For more information, see Populations.

    • Resources

      Resources represent the connections to external services, enabling secure access to PingOne resources and other defined external resources.

      For more information, see Resources, Resource scopes, and Resource attributes.

    • Activities

      Activities are collections of user activity information such as login attempts, password reset attempts, and total active user counts. This audit data can be exported, reported on, or streamed out to customer security information and event management (SIEM) solutions.

      For more information, see User activities.

    • Branding and images

      Branding can be configured for elements of the PingOne interface. All end user interfaces are branded according to the theme defined in the associated branding resource. Image resources can be configured to upload custom branding image files to the content delivery network (CDN) and manage the lifecycle of those images.

      For more information, see Branding and Images.

    • Password policies

      These resources represent the password management actions and password policies that can be applied to users within an environment.

      For more information, see Passwords.

    • Sign-on policies

      These resources represent the sign-on workflow policies to establish an authentication flow during login, re-authentication, or registration actions that identify and verify users. The authentication workflows are part of the authentication API. The signOnPolicy resource is a proxy back to other APIs to perform authentication actions.

      For more information, see Sign-on policies and Sign-on policy actions.

    • Notifications templates

      These endpoints manage notification templates resources and notifications content.

      For more information, see Notifications templates and Notifications settings.

    • Certificates and keys

      The certificate management endpoints provide an implementation that supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs. They manage customer-provided certificates, customer-provided signing/encryption keys, Ping-generated certificates (PKI), and Ping-generated signing/encryption keys.

      For more information, see Certificate management.

    Roles, entitlements, and permissions

    Roles, permissions, and entitlements are defined at the root of the platform. Roles are assigned to users, and these user roles include a scope property to grant the user permissions corresponding to the role. For example, a role of Identity Admin contains permissions allowing the subject to read and edit user data. When this role is assigned to a user, it can be assigned with the scope property that identifies a population or an environment to which the permissions apply.

    Self-service application permissions are described using scopes rather than roles. Scopes are more narrowly defined roles in that a scope cannot cross an environment boundary, and it is restricted to a specific task. For example, the p1:read:user scope grants permission to read the user resource's data only; it does not grant permission to read another user's data or perform create, update, or delete operations on user resources.

    For more information, see Roles and Resource scopes.

    Licenses

    The license resource identifies the organization that owns the license, the licensing package type, and the expiration date for the license.

    For more information, see Licensing.

    Administrator Security

    Use the administrator security endpoints to read and update environment administrator sign-on settings. By default, MFA is enforced for administrators. You can use the PUT operation to:

    • Use an external identity provider or a hybrid configuration by making a request to PUT {{apiPath}}/environments/{{envID}}/adminConfig and setting the authenticationMethod property.
    • Require MFA for all admin sign-ons. In this case, use PingOne as the value of authenticationMethod, set the mfaStatus value to ENFORCE, and the allowedMethods to the MFA methods you want to enable.

    See Configuring Administrator Security in the PingOne administrator documentation for more information.

    Administrator security data model

    Property Type Required? Mutable? Description
    allowedMethods Object Optional Mutable Indicates the methods to enable or disable for admin sign-on. Required properties are TOTP (temporary one-time password), FIDO2, and EMAIL.
    allowedMethods.EMAIL String Required Mutable Indicates whether to enable email for sign-on. Must be set to either {\"enabled\":true} or {\"enabled\":false}.
    allowedMethods.FIDO2 String Required Mutable Indicates whether to enable FIDO2 for sign-on. Must be set to either {\"enabled\":true} or {\"enabled\":false}.
    allowedMethods.TOTP String Required Mutable Indicates whether to enable TOTP for sign-on. Must be set to either {\"enabled\":true} or {\"enabled\":false}.
    authenticationMethod String Required Mutable Indicates whether to use PingOne MFA, an external IdP, or a combination of both for admin sign-on. Possible values are PINGONE, EXTERNAL, or HYBRID. The default is PINGONE.
    createdAt Date N/A Read-only The timestamp the resource was created.
    environment.id UUID N/A Read-only The ID of the environment.
    hasFido2Capabilities Boolean N/A Read-only Indicates whether the environment supports FIDO2 passkeys for MFA.
    isPingIDInBOM Boolean N/A Read-only Indicates whether the environment supports PingID for MFA.
    mfaStatus String Required Immutable This property must be set to ENFORCE as MFA is required for administrator sign-ons. This property applies only to the specified environment.
    provider.id UUID Optional Mutable The UUID of the external IdP, if applicable.
    recovery Boolean Required Mutable Indicates whether to allow account recovery within the admin policy.
    updatedAt Date N/A Read-only The timestamp the resource was last updated.

    Response codes

    Code Message
    200 Successful operation.
    201 Successfully created.
    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.

    Read Administrator Security

    Read Administrator Security Populations

    Update Administrator Security (External IdP)

    Update Administrator Security (Enhanced)

    Update Administrator Security Populations (Hybrid)

    Agreement Management

    Agreements define the details of an agreement to which end users provide consent. An agreement consists of these PingOne resources:

    • Agreements resources

      Defines the top level configuration for all the languages resources associated with the agreement. For more information, see Agreements Resources.

    • Language resources

      Defines the configuation for the locale and for the configuration that applies to all revision resources associated with the language. For more information, see Agreement Languages Resources.

    • Revisions resources

      Defines the specific version text (the agreement content) to manage the lifecycle of the agreement to which users provide consent. For more information, see Agreement Revisions Resources.

    Learn more in Agreements in the PingOne admin guide.

    Agreement configuration

    An agreement cannot be enabled unless it supports the default environment language. The agreement resource can have its enabled property set to true only if there is "agreement content to show" for the default environment language. If the enabled property on the agreement resource is false, the agreement cannot be presented to end users.

    The condition of having "agreement content to show" requires that at least the environment's default language is configured as an agreement language resource. The agreement language resource that supports the environment's default language must be enabled. The agreement language resource can have its enabled property set to true only if there is "localized content to show" configured on its associated agreement revisions resource. If the enabled property on the agreement language resource is false, the agreement language cannot be presented to end users. Remember, you must enable the agreement language resource that represents the environment's default language to enable the agreement. Additional agreement languages can also be configured and associated with the agreement.

    The agreement revision resource associated with an agreement language resource must have text content (and it can have optional buttons and checkboxes) configured on the resource to meet the "localized content to show" condition to enable the language. For the agreement revision to be active, the agreement revision's effectiveDate property must not be set to a future date. However, the effectiveDate value can be set to a future date, but the revision is inactive until the specified date.

    How agreement content is presented to users

    Agreement languages are defined by either the language code (for example, en) or the combination of language code and country code (for example, en-GB). For identifying languages, the API follows the tags for identifying languages described in RFC_4646. For selecting a language code to use in an agreement, the API follows the matching of language tags described in RFC_4647.

    When an agreement is active, languages are presented to the user in the following order:

    1. User preference: The end user receives agreement content in the language that matches the user's preferredLanguage property value.

    2. Browser preference: If the user's preferredLanguage is not configured (or enabled) as one of the supported agreement language resources for this agreement, the end user receives agreement content in the language associated with the browser's configured locale.

    3. Environment default language: If the browser's configured language is not one of the enabled agreement language resources for this agreement, then the agreement content is presented to the end user in the environment's default language.

    The following table shows an example of how the platform presents agreement languages to users, depending on the environment default language, the configured agreement languages, and the user's language preferences.

    Environment default language Configured agreement languages User preference languages (ordered) Language presented to user
    es en, es en-US, es en
    es en-GB, es en-US es
    es en, en-GB, es en-US, es, en-GB en
    Agreement consent history

    A user's consents to agreements do not expire by default, but they can be configured to designate a re-consent action based on a specified length of time or the active date of an agreement revision. An environment supports up to 100 agreement resources.

    Only the user's latest consent information is kept in the API. Agreement consent history is visible through audit reporting events. For more information about audit reporting, see Audit Activities.

    For example, to search for the consent history for a specific user to an agreement using the audit activities API, the query filter looks like this:

    recordedat ge "2020-12-11T22:13:41.838Z" and recordedat le "2021-06-09T21:13:41.838Z" and resources.type eq "user" and resources.id eq "<user-id>" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED")

    To search for consent history for an agreement (showing consents for all users), the query filter looks like this:

    recordedat ge "2020-12-11T22:11:54.484Z" and recordedat le "2021-06-09T21:11:54.484Z" and resources.id eq "<agreement-id>" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED")

    Use Cases

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    The audit reporting events applicable to agreement consent history are:

    Service Event
    agreements AGREEMENT.CREATED
    agreements AGREEMENT.UPDATED
    agreements AGREEMENT_LANGUAGE.CREATED
    agreements AGREEMENT_LANGUAGE.UPDATED
    agreements AGREEMENT_LANGUAGE_REVISION.CREATED
    agreements AGREEMENT_LANGUAGE_REVISION.DELETED
    users AGREEMENT_CONSENT.ACCEPTED
    users AGREEMENT_CONSENT.REVOKED
    users AGREEMENT_CONSENT.DECLINED
    agreements AGREEMENT_CONSENT.ACCEPTED
    agreements AGREEMENT_CONSENT.REVOKED
    agreements AGREEMENT_CONSENT.DECLINED
    agreements LOCALIZATION_STATUS.UPDATED

    Agreements Resources

    The agreements API defines the top level configuration for all the languages resources associated with the agreement. It implements functions to create, read, update, and delete agreement resources.

    Agreements data model
    Property Type Required? Mutable? Description
    consentCountsUpdatedAt Date N/A Read-Only The time the consent count metric was last updated. This value is typically updated once every 24 hours.
    description String Optional Mutable The description of the agreement.
    enabled Boolean Required Mutable The current enabled state of the agreement. The agreement must support the default language to be enabled. It cannot be disabled if it is referenced by a sign-on action. When an agreement is disabled, it is not used anywhere that it is configured across PingOne.
    environment.id String N/A Read-Only A string that specifies the environment associated with the agreement.
    expiredUserConsents Integer Required Read-Only The number of users who have consented to the agreement, but their consent has expired. This value is last calculated at the consentCountsUpdatedAt time.
    id String N/A Read-Only The agreement ID.
    name String Required Mutable The name of the agreement resource.
    reconsentPeriodDays Float Optional Mutable The number of days until a consent to this agreement expires.
    totalUserConsents Integer Required Read-Only The total number of users who have consented to the agreement. This value is last calculated at the consentCountsUpdatedAt time.
    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.

    Create Agreement

    Read All Agreements

    Read One Agreement

    Update Agreement

    Delete Agreement

    Agreement Languages Resources

    Agreement languages define the configuration for the locale and for the configuration that applies to all revision resources associated with the language.

    Agreement languages are defined by either the language code (for example, en) or the combination of language code and country code (for example, en-gb). For identifying languages, the API follows the tags for identifying languages described in RFC_4646. For selecting a language code to use in an agreement, the API follows the matching of language tags described in RFC_4647.

    The end user's language selection for the consent agreement is determined by these attributes in the following priority: (1) the user's preferred locale, (2) the browser locale, or (3) the default language for the environment.

    The agreement languages service implements functions to create, read, update, and delete agreement language resources.

    Agreement languages data model
    Property Type Required? Mutable? Description
    agreement String Required Read-Only A UUID that specifies the agreement resource associated with this language resource.
    currentRevision String Optional Read-Only A UUID that specifies the current revision associated with this language resource. The current revision is the one shown to users for new consents in the language.
    displayName String Required Mutable Used as the title of the agreement for the language presented to the user.
    enabled Date Required/Optional Mutable Maps directly with a language being enabled or displayed for the environment within the platform. When running Create Language, enabled value will be false whether or not this property is included. If the language is disabled at the environment level, this property if always false.
    id String Required Read-Only UUID that specifies the language ID.
    locale String Required Mutable The tag for identifying the language resource associated with this agreement consent (for example, en-US). For more information about language tags, see Tags for Identifying Languages.
    userExperience.acceptCheckboxText String Optional Mutable The text next to the "accept" checkbox in the end user interface. Accepted character are unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
    userExperience.continueButtonText String Optional Mutable The text of the "continue" button in the end user interface. Accepted character are unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
    userExperience.declineButtonText String Optional Mutable The text of the "decline" button in the end user interface. Accepted character are unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).
    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.

    Create Language

    Read All Languages

    Read One Language

    Update Language

    Delete Language

    Agreement Revisions Resources

    Agreement revisions define the specific version text (the agreement content) to manage the lifecycle of the agreement to which users provide consent.

    A revision resource allows you to update the content for an agreement language. (A language can have up to 100 associated revisions.) The revision must have a value specified for the effectiveDate property, and when showing content to a user for an agreement language, the content associated with a revision with an effective date closest to the current date is shown. The revision can be configured to force the user to consent again to the agreement.

    The revisions service implements functions to create, read, and delete agreement revision resources. Agreement revision resources cannot be updated. If an agreement revision needs to be updated, a new agreement revision should be created. In addition, agreement revision resources that have become effective cannot be deleted, which ensures that consent data is preserved.

    Revision data model
    Property Type Required? Mutable? Description
    agreement String Required Read-Only The UUID for the agreement resource for this revision.
    contentType String Required Immutable The content type of text. Options are text/html and text/plain, as defined by rfc-6838 and Media Types/text. This attribute is supported in POST requests only.
    effectiveAt Date Required Mutable The start date that the revision is presented to users. This property value can be modified only if the current value is a date that has not already passed. The effective date must be unique for each language agreement, and the property value can be the present date or a future date only.
    id String Required Read-Only The revision ID.
    language String Required Mutable A UUID that specifies the language resource associated with this revision.
    notValidAfter Date Optional Read-Only Specifies whether the revision is still valid in the context of all revisions for a language. This property is calculated dynamically at read time, taking into consideration the agreement language, the language enabled property, and the agreement enabled property. When a new revision is added, the notValidAfter property values for all other previous revisions might be impacted. For example, if a new revision becomes effective and it forces reconsent, then all older revisions are no longer valid.
    requiresReconsent Boolean Required Mutable Whether the user is required to provide consent to the language revision after it becomes effective.
    text String Required Immutable Text or HTML for the revision. HTML support includes:
    • tags - italicize, bold, links, headers, paragraph, line breaks
    • link (a) tags - allow href, style, target attributes
    • block tags (p, b, h) - allow style and align attributes
    This attribute is supported in POST requests only. For more information, see contentType.
    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.

    Create Revision

    Read All Revisions

    Read One Revision

    Delete Revision

    Migrate existing external agreement consents to PingOne

    This topic provides guidance on how to load existing user agreement consents into PingOne. It assumes that your users and agreements are already loaded into PingOne. For information about creating and managing users, see Users.

    In this topic, the following terms are used to describe the PingOne and external entities:

    • External user: A user record outside of PingOne.

    • External agreement: An agreement that exists outside of PingOne to which external users have provided consent.

    • External agreement consent: A user agreement consent record outside of PingOne.

    • PingOne user: The user in PingOne. You should have a way to correlate each external user to the corresponding PingOne user.

    • PingOne agreement: An agreement in PingOne. Each of your external agreements should have a corresponding PingOne agreement.

    • PingOne agreement consent: A user agreement consent record in PingOne.

    Migrate external agreement consents

    Follow these steps to load one existing external user agreement consent into PingOne:

    Step 1: Get information from the external existing consent record

    Extract the following information from your existing agreement consent record. You will need this information to complete Step 2:

    • userId

      The existing external consent should be associated with an external user. Correlate that external user to a PingOne user. The userId is that PingOne user's id.

    • agreementId

      The existing external agreement consent should be associated with an external agreement. Correlate that external agreement to a PingOne agreement. The agreementId is that PingOne agreement's id.

    • languageId

      The existing consent should be associated with a language. Correlate that to a PingOne agreement language. This is the PingOne agreement language languageId property value needed in the API request you will run in Step 2.

    • revisionId

      The most recent effective revision ID associated with the PingOne agreement language. This is the PingOne agreement revision revisionId property value needed in the API request you will run in Step 2.

    • consentedAt

      This can be either the external agreement consent time or the current time. If you want to make sure your users do not have to consent again, you might need to modify the PingOne agreement's reconsent period property.

    Step 2: Create the user's PingOne agreement consent

    To create the user's corresponding PingOne agreement consent, you can make requests to the following PingOne endpoint: POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/agreementConsents/{{agreementID}}. You will need the information for the external agreement consent you collected in Step 1.

    The POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/agreementConsents/{{agreementID}} request uses a Content-Type header with a value of application/vnd.pingidentity.consent.accept+json to initiate the consent accept action.

    The request body for this request requires the following properties:

    {
	language: { id: "{{languageID}}" },
	revision: { id: "{{revisionID}}" },
	consentedAt: "{{date}}"
}

    The languageID property value is the ID of the language resource associated with the agreement revision. The revisionID is the PingOne current active agreement revision ID.

    For more information about the POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/agreementConsents/{{agreementConsentID}} request, see Accept Agreement.

    To load multiple existing external user agreement consents into PingOne, you can perform this operation over your existing external agreement consents and load each one at a time. Please ensure you account for API rate limits.

    Alerting

    The Alerting service delivers warnings to administrators' email addresses regarding changes in resource states that can cause service disruptions. By default, each alert is sent only once. The Alerting service filters out any duplicate alerts.

    For administrators to receive these alerts, you must configure the alert channel to use for each environment. Currently, email is the only supported type of alert channel. Use the Alerting service endpoints to configure the alert channel.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    The audit reporting events applicable to the alerting service history are:

    Service Event
    alerting ALERT_CHANNEL.CREATED
    alerting ALERT_CHANNEL.UPDATED
    alerting ALERT_CHANNEL.DELETED

    Alert channel data model

    Property Type Required? Mutable? Description
    addresses String[] Required Mutable The administrator email addresses to send the alerts to.
    channelType String Required Mutable Alert channel type. Currently, this must be EMAIL.
    alertName String Optional Mutable The name to assign to the alert channel.
    environment.id String Required Immutable Unique ID of the environment.
    excludeAlertTypes String[] Optional Mutable Administrators will not be emailed alerts of these types. If empty, no alert types are excluded. Possible values are those listed for includeAlertTypes.
    id String N/A Read-only Unique ID of the alert channel.
    includeSeverities String[] Optional Mutable Filters alerts by severity. If empty, all severities are included. Possible values are INFO, WARNING, and ERROR.
    includeAlertTypes String[] Optional Mutable Use the includeAlertTypes array to specify the alert types you want to create. If empty, all alert types are included. Possible values are: CERTIFICATE_EXPIRED, CERTIFICATE_EXPIRING, KEY_PAIR_EXPIRED, KEY_PAIR_EXPIRING, GATEWAY_VERSION_DEPRECATED, GATEWAY_VERSION_DEPRECATING, LICENSE_90_PERCENT_USER_SOFT_LIMIT, LICENSE_EXPIRED, LICENSE_EXPIRING, LICENSE_ROTATED, LICENSE_USER_HARD_LIMIT_EXCEEDED, LICENSE_USER_SOFT_LIMIT_EXCEEDED, RISK_CONFIGURATION, SUSPICIOUS_TRAFFIC.

    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.
    404 The requested resource was not found.

    Create Alert Channel (Email)

    Read All Alert Channels per Environment

    Update Alert Channel

    Delete Alert Channel

    Bill of Materials (BOM)

    PingOne environments serve as the container for the products and services that are licensed for a specific customer deployment. The Bill of Materials (BOM) service references the products and standalone shared services associated with an environment, functioning like a product registry for the environment. You can optionally add up to five custom bookmarks for each product in the BOM. Users will be able to access these bookmarks from the PingOne dashboard.

    The Bill of Materials service is closely associated with the Environments and Licensing services. A PingOne environment contains the configuration options for a deployment, which can include any (or all) Ping Identity products. PingOne supports multiple environments, and each environment can have its own deployment configuration. You can use the Bill of Materials (BOM) service to retrieve a specified environment's BOM to show product details in the environment's current configuration. The service also includes a supported action to update the BOM with additional licensed PingOne products (or non-PingOne Ping Identity products) to fine-tune the environment's deployment capabilities.

    You need the Environment Admin role to get the Bill Of Materials for an environment. For more information about roles, see Roles.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    The audit reporting events applicable to the BOM service history are:

    Service Event
    environments ENVIRONMENT.CREATED
    environments ENVIRONMENT.UPDATED
    environments ENVIRONMENT.UPDATED

    Bill of Materials data model

    Property Type Required? Mutable? Description
    _links Object N/A Read-only HAL links.
    _links.href String N/A Read-only HAL link.
    _embedded Object N/A Read-only HAL embedded resources.
    solutionType String Optional Immutable The solution type selected when creating the environment. Ignored on PUT operations. The following values are supported:
    CIAM_TRIAL. The Customer trial experience. Indicates the Customer solution type, and the Solution Designer was selected.
    WF_TRIAL. The Workforce trial experience. Indicates the Workforce solution type, and the Solution Designer was selected.
    CUSTOMER. Indicates the Customer solution type was selected. This solution type uses PingOne MFA, rather than PingID.
    WORKFORCE. Indicates the Workforce solution type was selected. This solution type uses PingID, rather than PingOne MFA.
    products Array Required Immutable The products that comprise the environment.
    createdAt Date Time N/A Read-only Date and time the resource was created.
    updatedAt Date Time N/A Read-only Date and time the resource was last updated.

    Products data model

    Property Type Required? Mutable? Description
    id String Required Immutable The ID of the product. Ignored on PUT operations.
    type String Required Immutable The Ping Identity product type.
    Options for PingOne platform products are PING_ONE_MFA, PING_ONE_RISK (this name also represents the PingOne Protect product), PING_ONE_DAVINCI, PING_ONE_VERIFY, PING_ONE_CREDENTIALS, PING_ONE_AUTHORIZE, PING_ONE_PROVISIONING, and PING_ONE_BASE.
    The PING_ONE_BASE product represents the default set of services that an environment can use on the PingOne platform.
    Options for other Ping Identity products are PING_FEDERATE, PING_ACCESS, PING_DIRECTORY, PING_DATA_SYNC, PING_DATA_GOVERNANCE, PING_ONE_FOR_ENTERPRISE, PING_ID, PING_ID_SDK, PING_CENTRAL, PING_INTELLIGENCE, PING_ONE_FOR_SAAS, and PING_AUTHORIZE.
    description String Optional Mutable Description of the product or standalone service.
    console.href String Optional Mutable Link to your administrative console for the product, whether the product is in the PingOne platform, PingCloud, a private cloud, or on-premises. If specified, must be an RFC 2396-compliant URI with a maximum length of 1024 characters.
    softwareLicense Object Optional Immutable The Ping software license associated with this product.
    softwareLicense.id String Optional Immutable The UUID of the Ping software license associated with this product. This is not the SFDC external ID.
    deployment Object Optional Immutable The external resource associated with this product, containing state and settings related to the external resource.
    deployment.id String Optional Immutable The ID of the external resource associated with this product.
    bookmarks String[] Optional Mutable Custom bookmarks. Maximum of five bookmarks per product.
    bookmarks.name String Optional Mutable Name of the custom bookmark. The name must be unique among the product bookmarks and be 50 characters or fewer.
    bookmarks.href String Optional Mutable A valid URL for the bookmark.
    tags String[] Optional Mutable The set of tags for the PingOne products to be initially configured. The currently supported value is "DAVINCI_MINIMAL" (only valid when the product type is PING_ONE_DAVINCI). This indicates that DaVinci is to be configured with a minimal set of resources.

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Internal server error.

    Read One Bill of Materials

    Update Bill of Materials

    Branding

    The Branding service enables you to customize the display of your environment in the PingOne admin console for your organization, including both your organization's identifying information, as well as thematic display elements.

    Branding settings

    The Branding settings configure the company name and logo associated with an environment.

    Branding themes

    The Branding themes configure the thematic details, such as layout, color, and images (see also the Images service).

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    The audit reporting events applicable to branding history are:

    Service Event
    branding SETTINGS.CREATED
    branding SETTINGS.UPDATED
    branding THEME.CREATED
    branding THEME.UPDATED
    branding THEME.DELETED

    Branding Settings

    Branding settings control the default branding configuration applied to the environment, specifying the company name and default logo associated with an environment ID. If a branding configuration is not specified, the authentication sign-on screens use Ping Identity branding.

    Branding settings data model

    Property Type Required? Mutable? Description
    companyName String Optional Mutable The company name associated with the specified environment.
    logo Object Optional Mutable Contains the logo references.
    logo.href String Required Mutable The URL or fully qualified path to the logo file used for branding. Required when logo is specified.
    logo.id String Required Mutable The ID of the logo image. Required when logo is specified.

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Unexpected server error.

    Read Branding Settings

    Update Branding Settings

    Branding Themes

    Branding themes control the layout, color, and images for the authentication sign-on screens associated with a specified environment. PingOne provides several branding template themes that can be used as-is, or as a starting point for further customization. If a branding theme is not specified, the sign-on screens use Ping Identity default branding.

    Branding template configurations

    PingOne provides the following branding theme configurations. A branding theme template must be specified in the template property when creating a new branding theme resource:

    default

      {
    "name": "default",
    "color": {
      "button": "#2996cc",
      "buttonText": "#ffffff",
      "bodyText": "#686f77",
      "headingText": "#686f77",
      "link": "#2996cc",
      "card": "#ffffff",
      "background": "#ededed"
    },
    "image": {
      "background": ""
    },
    "meta": {
      "displayName": "Ping Default"
    }
  }

    focus

    {
    "name": "focus",
    "color": {
      "button": "#cb0020",
      "buttonText": "#ffffff",
      "bodyText": "#4a4a4a",
      "headingText": "#cb0020",
      "link": "#2996cc",
      "card": "#fcfcfc",
      "background": "#ededed"
    },
    "image": {
      "background": ""
    },
    "meta": {
      "displayName": "Focus"
    }
  }

    mural

    {
    "name": "mural",
    "color": {
      "button": "#61b375",
      "buttonText": "#ffffff",
      "bodyText": "#000000",
      "headingText": "#000000",
      "link": "#2996cc",
      "card": "#fcfcfc",
      "background": ""
    },
    "image": {
      "background": "https://assets.pingone.com/ux/branding-themes/0.1.0/mural/bg.jpg"
    },
    "meta": {
      "displayName": "Mural",
      "cssLink": "https://assets.pingone.com/ux/branding-themes/0.1.0/mural/mural.css"
    }
  }

    slate

    {
    "name": "slate",
    "color": {
      "button": "#fcfcfc",
      "buttonText": "#4a4a4a",
      "bodyText": "#4a4a4a",
      "headingText": "#4a4a4a",
      "link": "#4a4a4a",
      "card": "#fcfcfc",
      "background": ""
    },
    "image": {
      "background": "https://assets.pingone.com/ux/branding-themes/0.1.0/slate/bg.jpg"
    },
    "meta": {
      "displayName": "Slate",
      "cssLink": "https://assets.pingone.com/ux/branding-themes/0.1.0/slate/slate.css"
    }
  }

    split

    {
    "name": "split",
    "color": {
      "button": "#263956",
      "buttonText": "#ffffff",
      "bodyText": "#263956",
      "headingText": "#686f77",
      "link": "#2996cc",
      "card": "#fcfcfc",
      "background": "#2996cc"
    },
    "image": {
      "background": ""
    },
    "meta": {
      "displayName": "Split"
    }
  }
    Branding themes data model
    Property Type Required? Mutable? Description
    configuration.backgroundColor String Required Mutable The background color for the theme. It must be a valid hexadecimal color code, and it is a required property when configuration.backgroundType is set to COLOR.
    configuration.backgroundType String Required Mutable The background type for the theme. Options are NONE, COLOR, IMAGE, DEFAULT.
    configuration.backgroundImage.href String Required Mutable The URL or fully qualified path to the background image file used for branding. This is a required property when configuration.backgroundType is set to IMAGE.
    configuration.backgroundImage.id String Required Immutable The ID of the background image.
    configuration.bodyTextColor String Optional Mutable The body text color for the theme. It must be a valid hexadecimal color code.
    configuration.buttonColor String Optional Mutable The button color for the theme. It must be a valid hexadecimal color code.
    configuration.buttonTextColor String Optional Mutable The button text color for the branding theme. It must be a valid hexadecimal color code.
    configuration.cardColor String Optional Mutable The card color for the branding theme. It must be a valid hexadecimal color code.
    configuration.footer String Optional Mutable The footer of the branding theme.
    configuration.headingTextColor String Optional Mutable The heading text color for the branding theme. It must be a valid hexadecimal color code.
    configuration.linkTextColor String Optional Mutable The hyperlink text color for the branding theme. It must be a valid hexadecimal color code.
    configuration.logo.href String Required Mutable The URL or fully qualified path to the logo file used for branding. This is a required property when configuration.logoType is set to IMAGE.
    configuration.logo.id String Required Immutable The ID of the logo image.
    configuration.logoType String Required Mutable The type of format used for the image. Options are IMAGE and NONE.
    configuration.name String Optional Mutable The name of the branding theme.
    default Boolean Required Mutable Specifies whether this theme is the environment's default branding configuration.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the branding theme.
    id String Required Immutable The ID of the branding configuration resource.
    template String Required Mutable The template name of the branding theme associated with the environment. Options are default, focus, mural, slate, and split.
    Response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    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.
    500 Unexpected server error.

    Create Branding Theme

    Read Branding Themes

    Read One Branding Theme

    Read Branding Theme Default

    Update Branding Theme

    Update Branding Theme Default

    Delete Branding Theme

    Capabilities

    The capabilities service provides operations to determine what an organization or an environment is capable of doing within PingOne with respect to:

    • The organization's current PingOne license.

    • The current utilization of PingOne resources.

    • The current PingOne system limits.

    • The products and services included in the environment's bill of materials.

    The Capabilities service is closely associated with the Licenses and Bill of Materials (BOM) services. The PingOne license and BOM identify the Ping Identity products associated with your organization and environment, but these services do not enumerate the specific actions you can perform. You can use the capabilities service to check the capabilities provided by the current license and the environment's BOM. For example, if the organization-level capability canCreateEnvironment is set to true, it shows that the license grants you the capability to create new environments. Likewise, there can be numerous capabilities at the environment level, depending on the products in the BOM. The following list shows some of the actions that you might be able to perform:

    "canUseCredentials": false,
"canUseCredentialsPushNotifications": false,
"canUseCustomSchema": true,
"canUseDaVinciAdminPortal": true,

    In this case, you can implement a custom user schema and you can access the DaVinci admin portal, but you cannot perform actions that use credentials or credential-based push notifications.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    The audit reporting events applicable to the capabilities service history are:

    Service Event
    capabilities ENVIRONMENT.CAPABILITIES
    capabilities ORGANIZATION.CAPABILITIES

    Organization capabilities data model

    Property Type Required? Mutable? Description
    assignableLicenses.allowProduction Boolean Required Read-only Whether the license allows production environments.
    assignableLicenses.beginsAt Date Required Read-only When the license period starts.
    assignableLicenses.expiresAt Date Required Read-only When the license period ends.
    assignableLicenses.id String Required Read-only The license ID for a license that can be assigned to the organization.
    assignableLicenses.name String Required Read-only The name of a license that can be assigned to the organization.
    assignableLicenses.supportedRegions Array [String] Required Read-only The names of the supported regions for a license that can be assigned to the organization.
    canContactSupport Boolean Required Read-only Whether the organization can contact PingOne support.
    canCreateEnvironment Boolean Required Read-only Whether the organization can create an environment. A return value of false specifies that the organization's maximum number of environments has been reached.
    canCreateEphemeralTrialLicenses Boolean Required Read-only Whether the organization can create short-term trial licenses.
    canUsePlatform Boolean Required Read-only The status of the associated license. Return values are true (ACTIVE) and false (TERMINATED).
    organizationId String Required Read-only The ID of the organization.

    Environment capabilities data model

    Property Type Required? Mutable? Description
    canAddResources Boolean Required Read-only Whether the license supports creation of resources in the specified environment.
    canAssignUsersRoles Boolean Required Read-only Whether the license supports role assignments in the specified environment.
    canContactSupport Boolean Required Read-only Whether the license allows contact of PingOne Support.
    canCreateConnections Boolean Required Read-only Whether the license supports creation of a application connections in the specified environment.
    canCreateCustomDomain Boolean Required Read-only Whether the license supports creation of a custom domain in the specified environment.
    canPromoteToProd Boolean Required Read-only Whether the environment's type property can be promoted from SANDBOX to PRODUCTION.
    canSendMfaNotificationsOutsideWhitelist Boolean Required Read-only Whether the license supports sending notifications outside of the environment's whitelist.
    canSendPasswordManagementNotifications Boolean Required Read-only Whether the license supports sending password management notifications.
    canSendVerificationFlowNotifications Boolean Required Read-only Whether the license supports sending verification flow notifications.
    canUseAamva Boolean Required Read-only Whether the license supports using additional verification support with American Association of Motor Vehicle Administrators (AAMVA).
    canUseAamvaTransactions Boolean Required Read-only Whether the license supports using AAMVA transactions.
    canUseAccountProtection Boolean Required Read-only Whether the license supports using account protection.
    canUseAccountTakeoverDetection Boolean Required Read-only Whether the license supports using account takeover detection.
    canUseApiAccessManagement Boolean Required Read-only Whether the license supports using API Access Management services.
    canUseBotMaliciousDeviceDetection Boolean Required Read-only Whether the license supports using malicious BOT device detection capabilities.
    canUseCredentialSharingDetection Boolean Required Read-only Whether the license supports using credential sharing detection capabilities.
    canUseCredentials Boolean Required Read-only Whether the license supports using credentials services.
    canUseCredentialsPushNotifications Boolean Required Read-only Whether the license supports using credentials push notifications services.
    canUseCustomSchema Boolean Required Read-only Whether the license supports using custom schema tributes in the specified environment.
    canUseDaVinciAdminPortal Boolean Required Read-only Whether the license supports using the DaVinci admin portal.
    canUseDataAnalyticsSupport Boolean Required Read-only Whether the license supports using data analytics support services.
    canUseDigitalVerifications Boolean Required Read-only Whether the license supports using digital verifications services.
    canUseDocumentMatch Boolean Required Read-only Whether the license supports using document match services.
    canUseDynamicAuthorization Boolean Required Read-only Whether the license supports using dynamic authorization services.
    canUseEmailOtp Boolean Required Read-only Whether the license supports using email OTP capabilities.
    canUseFaceMatch Boolean Required Read-only Whether the license supports using face match capabilities.
    canUseFraudDataEnrichment Boolean Required Read-only Whether the license supports using fraud data enrichment capabilities.
    canUseIdentities Boolean Required Read-only Whether the license supports using identities.
    canUseIdentityProviders Boolean Required Read-only Whether the license supports using external identity providers in the specified environment.
    canUseInboundProvisioning Boolean Required Read-only Whether the license supports using inbound provisioning services.
    canUseIntelligence Boolean Required Read-only Whether the license supports using PingIntellegence capabilities in the specified environment. This capability applies to the PingOne Platform and PingOne MFA products.
    canUseIntelligenceAdvancedPredictors Boolean Required Read-only Whether the license supports using PingIntellegence advanced predictors capabilities in the specified environment. This capability applies to the PingOne Platform and PingOne MFA products.
    canUseIntelligenceAnonymousNetworkDetection Boolean Required Read-only Whether the license supports using PingIntellegence anonymous network detection capabilities in the specified environment. This capability applies to the PingOne Platform and PingOne MFA products.
    canUseIntelligenceDataConsent Boolean Required Mutable Whether the customer consents to user and event behavior analytics (UEBA) collection capabilities in the specified environment. This capability applies to the PingOne Protect product.
    canUseIntelligenceGeoVelocity Boolean Required Read-only Whether the license supports using PingIntellegence geovelocity capabilities in the specified environment when a geovelocity anomaly is detected. This capability applies to the PingOne Platform and PingOne MFA products.
    canUseIntelligenceProtect Boolean Required Read-only Whether the license supports using protect capabilities in the specified environment. This capability applies to the PingOne Protect product.
    canUseIntelligenceReputation Boolean Required Read-only Whether the license supports using PingIntellegence reputation capabilities in the specified environment. This capability applies to the PingOne Platform and PingOne MFA products.
    canUseIntelligenceRisk Boolean Required Read-only Whether the license supports using Risk capabilities in the specified environment. This capability applies to the PingOne Protect product.
    canUseKerberosGateway Boolean Required Read-only Whether the license supports using Kerberos gateway services.
    canUseLdapGateway Boolean Required Read-only Whether the license supports using LDAP gateway services.
    canUseManualIDStepUpInspection Boolean Required Read-only Whether the license supports using manual ID step-up inspection services.
    canUseManualIdInspection Boolean Required Read-only Whether the license supports using manual ID inspection services.
    canUseMfa Boolean Required Read-only Whether the license supports using MFA in the specified environment.
    canUseMfaFido2Devices Boolean Required Read-only Whether the license supports MFA operations on FIDO2 devices.
    canUseMfaPushNotifications Boolean Required Read-only Whether the license supports MFA push authentication for native applications in the specified environment.
    canUseMfaVoiceOtp Boolean Required Read-only Whether the license supports MFA voice OTP for native applications in the specified environment.
    canUseMyAccount Boolean Required Read-only Whether the license supports using the My Account capabilities in the specified environment.
    canUseNewAccountFraudDetection Boolean Required Read-only Whether the license supports using new account fraud detection capabilities in the specified environment.
    canUseOrchestration Boolean Required Read-only Whether the license supports using orchestration capabilities in the specified environment.
    canUsePasswordManagement Boolean Required Read-only Whether the license supports using password management capabilities in the specified environment.
    canUsePasswordOnlyAuthentication Boolean Required Read-only Whether the license supports using password only login capabilities in the specified environment.
    canUsePasswordPolicy Boolean Required Read-only Whether the license supports using password policies in the specified environment.
    canUsePlatform Boolean Required Read-only The status of the associated license. Return values are true (ACTIVE) and false (TERMINATED).
    canUseProtectTransactions Boolean Required Read-only Whether the license supports using protect transaction capabilities in the specified environment.
    canUseProvisioning Boolean Required Read-only Whether the license supports using provisioning capabilities in the specified environment.
    canUseRadiusGateway Boolean Required Read-only Whether the license supports using radius gateway services.
    canUseSmsOtp Boolean Required Read-only Whether the license supports using SMS OTP capabilities.
    canUseTotp Boolean Required Read-only Whether the license supports using TOTP capabilities.
    canUseVerificationFlow Boolean Required Read-only Whether the license supports using verification flows in the specified environment.
    canUseVerify Boolean Required Read-only Whether the license supports using Verify in the specified environment.
    canUseVerifyPushNotifications Boolean Required Read-only Whether the license supports using verify push notifictions capabilities in the specified environment.
    canUseVerifyVoice Boolean Required Read-only Whether the license supports using verify voice capabilities in the specified environment.
    canUseVoiceBiometrics Boolean Required Read-only Whether the license supports using biometric voice capabilities in the specified environment.
    canUseUniversalCapture Boolean Required Read-only Whether the license supports using universal capture capabilities in the specified environment.
    canUsersUpdateSelf Boolean Required Read-only Whether the license supports allowing users to update their own profile.
    environmentId String Required Read-only The ID of the environment.

    Response codes

    Code Message
    200 Successful operation.
    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 Organization Admin role or the Environment Admin role to get the capabilities for an organization or an environment, respectively. For more information about roles, see Roles.

    Read Organization Capabilities

    Read Environment Capabilities

    Certificate Management

    The certificate management service manages two types of records, keys and certificates. Keys represent a key pair that consists of a private key and a public key. A certificate represents the electronic document used to verify the owner of the public key. This service supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs, and manages:

    • Customer-provided certificates
    • Customer-provided signing and encryption keys
    • PingOne-generated certificates (PKI)
    • PingOne-generated signing and encryption keys
    • Key rotation policies

    The certificate management service also manages encryption and decryption operations, as well as signing and validation operations.

    To use any of the PingOne signing and encryption features, you'll need to either provide a certificate you've generated, or configure the options for a PingOne-signed certificate. When uploading certificates, the certificate must be valid at the time of upload. You cannot upload a certificate before its validity period begins (the certificate's NotBefore date), or after it expires (the certificate's NotAfter date). The private key must be unencrypted. You cannot upload a private key that is protected by a password or passphrase. The certificate, private key, and certificate chain must all be PEM-encoded unless uploading a PKCS12 file format.

    Default organization and environment certificates

    The certificate management service creates default certificates for PingOne organization, and environment resources.

    Default organization certificate

    The certificate management service listens for the "create organization" event, and when the organization is created, the certificate management service creates a default intermediate CA signing certificate for the organization resource. This default org certificate is used to sign all environment certificates.

    The default organization certificate includes the following values:

    Property Value
    version V3 (2)
    serialNumber Secure Random generated
    algorithmID sha256WithRSAEncryption
    issuer commonName: Ping Identity v2; organizationalUnit: www.pingidentity.com; organization: Ping Identity Corporation; country: US
    subject commonName: value; Organization Name: value; organizationalUnit: value; organization: value; country: value
    validity not before: current date, not after: 1 year from current date
    extensions none

    Default environment certificate

    The service also listens for "create environment" events and creates the default key and certificate for the environment resource. The default organization certificate signs all environment certificates.

    The default environment certificate includes the following values:

    Property Value
    version V3 (2)
    serialNumber Secure Random generated
    algorithmID sha256WithRSAEncryption

    Default environment key

    The default environment key includes the following values:

    Property Value
    algorithm RSA
    validity period 1 year
    key length 2048

    Certificate management data model

    Property Type Required? Mutable? Description
    algorithm String Required Immutable The key algorithm. Options are RSA, EC, and UNKNOWN.
    createdAt Date N/A Read-only The time the resource was created.
    default Boolean Required Mutable Indicates whether this is the default key for the specified environment.
    environment.id String Required Immutable Specifies the environment resource’s unique identifier.
    expiresAt Date N/A Read-only The time the key resource expires.
    id String Required Immutable The resource’s unique identifier.
    issuerDN String Required Mutable The distinguished name (DN) of the certificate issuer.
    keyLength Integer Required Immutable The key length. For RSA keys, options are 2048, 3072, 4096, and 7680. For elliptical curve (EC) keys, options are 224, 256, 384, and 521.
    name String Optional Mutable The resource name.
    organization.id String Required Immutable The organization resource’s unique identifier.
    serialNumber Integer Required Immutable The serial number of the key or certificate.
    signatureAlgorithm String Required Immutable The signature algorithm of the key. Options are SHA256withRSA and SHA512withRSA.
    startsAt Date Required Immutable The time the validity period starts.
    status String N/A Read-only The status of the key. Options are VALID, EXPIRED, NOT_YET_VALID, and REVOKED. If the current time is within 2 weeks of the expiration date, the status is EXPIRING.
    subjectDN String Required Immutable The DN of the subject being secured.
    trustChain String[] Optional Mutable An array of PEM-encoded X509 Certificates that are in the trust chain of the key's chain of trust.
    usageType String Required Mutable Specifies how the certificate is used. Options are ENCRYPTION, SIGNING, ISSUANCE, SSL_TLS, and OUTBOUND_MTLS. ISSUANCE keys are used as part of another key's trust chain, and are used to sign other keys. Certificate Revocation Lists (CRL) are published against these keys. SSL_TLS keys are used to protect internet protocol domains (such as, a Custom Domain you've configured in PingOne). OUTBOUND_MTLS keys are used to enable mutual TLS (mTLS) authentication with a subscription service.
    validityPeriod Integer Required Immutable The number of days the key is valid.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    keystores KEYSTORE.CREATED

    Response codes

    Code Message
    200 Successful operation.
    201 Successfully created.
    204 Successfully removed. No content.
    400 The request could not be completed.
    404 The requested resource was not found.

    Key Rotation Policies

    The certificate management service supports automatically rotating key pairs. Administrators can update certificates with minimal intervention, eliminating many common configuration errors.

    Resources called key rotation policies (KRPs) are exported through the PingOne API by the Certificate Management service. KRPs manage a set of key pairs that are created and rotated on a scheduled basis. These key pairs are referred to as KrpKeys to distinguish them from existing key pair resources. The cryptographic details of KrpKeys are managed by a specification attached to the KRP. The specification includes settings such as algorithm, key length, validity duration period, and distinguished name (DN). This specification and the rotation schedule are mutable after creation. Generated KrpKeys are always self-signed with no extraordinary extensions.

    When an environment is created, PingOne creates an initial KRP configuration object as the default KRP. You can can create additional KRPs using the POST {{apiPath}}/environments/{{envID}}/keyRotationPolicies operation. There is no UI to manage KRPs in the PingOne admin console. PingOne allows up to five KRPs per environment. You won't be able to create a new KRP if the environment already has five KRPs. You cannot delete the default KRP for an environment. A DELETE operation won’t succeed if the environment has only one KRP.

    At any given time, a KrpKey has one of three designations: PREVIOUS, CURRENT, or NEXT. When created, a KRP has two KrpKeys with designations CURRENT and NEXT, respectively. After a period of time defined by a KRP’s rotation schedule, a new KrpKey is created and designated as NEXT. The KrpKey previously designated as NEXT transitions to CURRENT, and the KrpKey previously designated as CURRENT transitions to PREVIOUS.

    A KRP exports another operation to list all KrpKeys that it manages. This is a read-only operation that returns a JSON Web Key set (JWKS) formatted file containing all public keys associated with a KrpKey managed by a KRP. This allows downstream clients to cache any public keys for use during signature validation. This operation is public and does not require an authentication token.

    Key Rotation Policy data model

    Property Type Required? Mutable? Description
    algorithm String Required Mutable The algorithm this KRP applies to generated KrpKeys. RSA is currently the only supported value.
    currentKeyId UUID N/A Read-only The kid (key identifier) of the KrpKey designated as CURRENT.
    dn String Required Mutable The DN this KRP will apply to generated KrpKeys. Is applied as both issuerDN and subjectDN because generated KrpKeys are self-signed.
    id UUID N/A Read-only Unique identifier of the KRP.
    environment.id UUID N/A Read-only Unique identifier of the environment that the KRP belongs to.
    keyLength Integer Required Mutable The number of bytes of a cryptographic key this KRP will apply to generated KrpKeys.
    name String Required Mutable Human-readable name displayed in the admin console.
    nextKeyId UUID N/A Read-only The kid (key identifier) of the KrpKey designated as NEXT.
    rotatedAt Date N/A Read-only The last time this KRP was rotated.
    rotationPeriod Integer Optional Mutable The number of days to elapse before this KRP rotates KrpKeys. The default value is 90 days. The minimum value is 30 days. The maximum value is 1 day less than the validityPeriod value.
    signatureAlgorithm String Required Mutable The signature algorithm this KRP will apply to generated KrpKeys. SHA256withRSA is currently the only supported value.
    usageType String Required Mutable How the KRP will be used, pertaining to what operations the KRP supports. The only valid value for initial release is SIGNING.
    validityPeriod Integer Required Mutable Controls the startsAt and expiresAt fields this KRP will apply to generated KrpKeys. The default value is 365 days.

    Signing Request data model

    Property Type Required? Mutable? Description
    document String Required Mutable Base64-encoded binary document to sign.
    signatureAlgorithm String Optional Mutable If present, this value overrides the signatureAlgorithm setting of the CURRENT KrpKey. SHA256withRSA is currently the only supported value.

    Signing Response data model

    Property Type Required? Mutable? Description
    key Object N/A Read-only KrpKey delegated to perform the sign operation. This KrpKey is always designated as CURRENT rotation state.
    key.id UUID N/A Read-only Unique identifier of the KrpKey.
    signature String N/A Read-only Base64-encoded signature (MAC) as the result of the signing operation.
    signatureAlgorithm String N/A Read-only The signature algorithm used to perform the sign operation. SHA256withRSA is currently the only supported value.
    Response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    204 Successfully removed. No content.
    400 The request could not be completed.
    404 The requested resource was not found.
    500 An unexpected error occurred.

    Create Key Rotation Policy

    Get Key Rotation Policies

    Get JWKS for Key Rotation Policy

    Update Key Rotation Policy

    Delete Key Rotation Policy

    Create Key

    Create Key with PKCS12 File

    Create Certificate with PKCS7 or PEM File

    Get Keys

    Get Certificates

    Get Key

    Get Key Applications

    Get Certificate

    Get Certificate Applications

    Export Public Key (PKCS7 DER)

    Export Public Key (X509 PEM)

    Export a Certificate Signing Request (CSR)

    Update Key

    Import Certificate Authority (CA) Response to a CSR

    Delete Key

    Delete Certificate

    Custom Domains

    PingOne supports the mapping of customer-owned and controlled domain names that are used to access user interfaces and services. You have the ability to route your own domain name alias to PingOne hosts, removing all references to “pingone” in the URLs (including the environment ID).

    Companies typically consider domain names associated with their company as essential and valuable brand assets. They do not want vendor domains visible on sites visited by their customers. If a request to a vendor is visible to their customers, such as authentication requests to Ping Identity, companies want the domain in that request to be a corporate domain and not a vendor domain (for example: auth.pingone.com).

    The custom domain feature enables such domain substitution.

    Custom domains are not applicable to:

    • api.pingone

    • scim-api.pingone

    • orchestrate-api.pingone

    • uploads*.pingone

    Custom domains can be applied to:

    • The https://auth.pingone.com domain. For example:

      • https://auth.pingone.com/{{envID}}/* becomes {{customDomain}}/*.

      • https://auth.pingone.asia/{{envID}}/as/authorize becomes {{customDomain}}/as/authorize.

    • The https://apps.pingone.com domain. For example:

      • https://apps.pingone.com/{{envID}}/myapps/ becomes {{customDomain}}/myapps.

      • https://apps.pingone.com/{{envID}}/myaccount/ becomes {{customDomain}}/myaccount.

      • https://apps.pingone.com/{{envID}}/signon/?flowId={{flowID}} becomes {{customDomain}}/signon/?flowId={{flowID}}

    For example, if your company domain is acme.com and you want to use auth.acme.com for your custom domain, you can create a custom domain resource, passing in auth.acme.com. When the custom domain resource is created, the status value is set to VERIFICATION_REQUIRED and the response returns a canonicalName property value that looks similar to this: 1234-abcd-5678-efgh.edge1.pingone.com. However, before you can verify the domain, you must first create a record with the Domain Name System (DNS) to describe how traffic is routed for the domain. The DNS record identifies the domain, and it requires a CNAME record value, which is a name-value pair consisting of your domain name pointing to the PingOne canonicalName property value returned by the create request. In this example, the CNAME record resolves auth.acme.com to the canonical name, 1234-abcd-5678-efgh.edge1.pingone.com.

    After defining the CNAME record in the Domain Name System, you can verify the domain using the POST {{apiPath}}/environments/{{envID}}/customDomains/{{customDomainID}} request with the application/vnd.pingidentity.domainName.verify+json custom media type (and an empty request body). Be aware that after entering the CNAME record, it can take some time to propagate to the DNS servers, which can result in a request failure during this period. When successful, the response returns a status of SSL_CERTIFICATE_REQUIRED, which requires an SSL certificate import action.

    To import the certificate, you can run the POST {{apiPath}}/environments/{{envID}}/customDomains/{{customDomainID}} request again using the application/vnd.pingidentity.certificate.import+json custom media type in the request header. The body for this request must specify the certificate, the certificate chain, and the private key. If successful, the response returns a status of ACTIVE to indicate that the custom domain has been verified and is active. Again, be aware that it can take some time before the custom domain is operational.

    If you do not have an SSL certificate for the custom domain, see Generate a CSR for custom domains below for information about generating an SSL certificate.

    Generate a CSR for custom domains

    If you use a custom domain, you need to create the custom domain resource in PingOne and import the SSL certificate used by the custom domain resource. In brief, the steps in PingOne to implement a custom domain are:

    1. Create the custom domain resource (for example, auth.acme.com).

    2. Create a CNAME record in the acme.com DNS for auth.acme.com that points to the canonical name when the custom domain was created.

    3. If you do not have an SSL certificate, outside of PingOne, generate a certificate for auth.acme.com (a certificated request that is signed by a certificate authority), which results in a private key, certificate chain, and certificate.

    4. Import the SSL certificate (chain, cert, private key).

    Generate an SSL certificate

    If you do not have an SSL certificate, which is referenced in step 3, follow these steps to create the trusted SSL certificate for the custom domain:

    1. Open (or install) openssl on your computer.

    2. Enter the following openssl command:

      openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr

    3. Enter the following certificate signing request (CSR) information at the prompt:

      • Common Name (CN)
      • Organization
      • Organization Unit (OU)
      • City (or Locality)
      • State (or Province)
      • Country

    4. Submit your CSR to a Certificate Authority (CA) for validation.

    After validation, the CA returns the trusted SSL certificate, which you can import to complete and enable the custom domain. For information about custom domains, see Custom Domains.

    Custom domains data model

    Property Type Required? Mutable? Description
    certificate Object N/A Read-only Contains information about the SSL certificate used by this custom domain. If this property is not present, it indicates that an SSL certificate has not been setup for this custom domain.
    canonicalName String N/A Read-only The UUID of the domain name used as the value of the CNAME record in the customer’s DNS. In a response, PingOne resolves this to ".edge1.pingone.com".
    certificate.expiresAt Date N/A Read-only The time when the certificate expires.
    domainName String Required Immutable The resource name, which must be provided and must be unique within an environment (for example, auth.shopco.com).
    environment.id String Required Immutable The UUID of the environment associated with the resource.
    id String N/A Read-only The UUID of the custom domain.
    status String N/A Read-only The status of the custom domain. Options are ACTIVE, VERIFICATION_REQUIRED, and SSL_CERTIFICATE_REQUIRED.

    SSL certificate import request data model

    Property Type Required? Mutable? Description
    certificate String Required Mutable The PEM-encoded certificate to import. The following validation is performed on the certificate:
    • It must not be expired.
    • It MUST not be self signed.
    • The custom domain name MUST match one of the subject alternative name (SAN) values on the certificate.
    intermediateCertificates String Required Mutable The PEM-encoded certificate chain.
    privateKey String Required Mutable The PEM-encoded, unencrypted private key that matches the certificate's public key.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    branding CUSTOM_DOMAIN.CREATED
    branding CUSTOM_DOMAIN.UPDATED
    branding CUSTOM_DOMAIN.DELETED

    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.
    404 The requested resource was not found.

    Create Domain

    Verify Domain

    Import Certificate

    Read All Domains

    Read One Domain

    Delete Domain

    Environments

    Every organization contains at least one environment resource. In large global enterprises, there can be several environments. These environments are often based on region, or they serve as the defining entity to segregate enterprise operations by functionality, staging environments, or configurations.

    An environment also identifies the products and services that are enabled to address the deployment requirements. For example, an environment can identify enabled PingOne services that are hosted on the PingOne platform, such as PingOne MFA and PingOne Protect. The environment can also identify supported non-PingOne products, such as PingFederate and PingAccess.

    An environment is the primary subdivision of an organization and contains the core resources on which all identity services are built.

    You can learn more about environments in Environment Properties.

    Environment types

    There are two supported environment types:

    • PRODUCTION

      These environments contain the actual identities managed by your business. You must have a non-Trial license to create or promote an environment to the PRODUCTION type. Any long-standing environments, even those used for testing and staging, should be configured as PRODUCTION to minimize the risk of data loss. PRODUCTION environments cannot be immediately deleted, but must transition through a soft delete state with a waiting period before completing the delete operation (hard delete). See Deleting environments below.

    • SANDBOX

      These environments are temporary configurations used primarily for configuration testing. Sandbox environments can be immediately deleted using the DELETE {{apiPath}}/environments/{{envID}} request. A Sandbox environment cannot be restored.

    Environments and product types

    You'll find the product types (both PingOne and non-PingOne) that can be associated with a new environment in the type property of the Bill of Materials Products data model.

    Roles and environments

    You need the Environment Admin role to perform operations on environment resources. To create environments, you must have either an Organization Admin role or an Environment Admin role at the organization level. An Environment Admin role at the environment level (applicable to a specific environment) cannot create new environments.

    The role assignment scope determines the domain of the role. For example, the following role assignment resource shows that this Environment Admin role has a scope that applies only to an environment. An actor with this Environment Admin role cannot create a new environment.

    "scope": {
    "id": "{{envID}}",
    "type": "ENVIRONMENT"
},
"role": {
    "id": "{{environmentAdminRoleID}}"
}

    Conversely, an actor with an Environment Admin role assignment scope that specifies the organization resource can create new environments. For example, the scope id for the following role assignment designates an organization resource ID as the scope domain. An Environment Admin with this role assignment scope has permission to create new environments.

    "scope": {
    "id": "{{orgID}}",
    "type": "ORGANIZATION"
},
"role": {
    "id": "{{environmentAdminRoleID}}"
}

    For additional information about role assignment scopes, see Application role assignments and User role assignments.

    Deleting environments

    You can delete a PRODUCTION environment if you have the Environment Admin role at the organization level, or the Organization Admin role. To delete an environment, use the Update Environment Status request, and set the status to DELETE_PENDING. This is called a soft delete. An environment that's been soft-deleted is not operational.

    SANDBOX environments are intended to be temporary, and are immediately deleted by calling the DELETE {{apiPath}}/environments/{{envID}} request. These environments cannot be restored.

    An Production environment with a status of DELETE_PENDING is automatically set to a waiting period before complete deletion is possible. The waiting period duration is the time the environment was set to DELETE_PENDING (reflected in the softDeletedAt value) plus a period of 30 days. When the waiting period has elapsed, you can then call the Delete Environment request to fully delete (hard delete) the environment. The time remaining for a hard delete to be possible is reflected in the hardDeleteAllowed At value. If at the time of the hard delete attempt the waiting period has not elapsed, the Delete Environment request will throw an error with the time the environment can be hard-deleted.

    Restoring environments

    You can restore a Production environment having a DELETE_PENDING status if you have the Environment Admin role at the organization level, or the Organization Admin role. To restore an environment, use the Update Environment Status request, and set the status to ACTIVE. You'll also need to specify your PingOne license ID.

    Audit reporting events

    See Audit Reporting Events for all Environment service events.

    Environments data model

    Property Type Required? Mutable? Description
    billOfMaterials Object Optional Mutable The Bill of Materials for the environment. This is an optional property. Create requests that do not specify this property receive a default PingOne Bill of Materials on creation. For more information, see Bill of Materials.
    billOfMaterials.products[0] Array Optional Mutable Products that specify the PingOne and non-PingOne products and services that are associated with this environment deployment.
    billOfMaterials.products[0].id String Required Immutable The Product's ID.
    billOfMaterials.products[0].type String Optional Mutable The Product type. Options for PingOne products are PING_ONE_MFA, PING_ONE_RISK, PING_ONE_PROVISIONING, and PING_ONE_BASE. Options for non-PingOne product are PING_FEDERATE, PING_ACCESS, PING_DIRECTORY, PING_DATA_SYNC, PING_DATA_GOVERNANCE, PING_ONE_FOR_ENTERPRISE, PING_ID, PING_ID_SDK, PING_CENTRAL, and PING_INTELLIGENCE.
    billOfMaterials.products[0].description String Optional Mutable The product's description.
    billOfMaterials.products[0].console String Optional Mutable The URL to the product's admin console.
    billOfMaterials.products[0].softwareLicense.id String Optional Immutable The software license ID associated with this product.
    billOfMaterials.products[0].deployment.id String Optional Immutable The external resource ID associated with this product, containing state and settings information related to the external resource associated with this product.
    createdAt Date N/A Read-only The time the resource was created.
    description String Optional Mutable The description of the population.
    hardDeletedAllowedAt Date N/A Read-only The time when the soft-deleted Production environment (set to DELETE_PENDING status) can be completely deleted (a hard delete). When a soft-deleted environment is restored, this value is cleared.
    icon String Optional Mutable The URL referencing the image to use for the environment icon. The supported image types are JPEG/JPG, PNG, and GIF.
    id String Required Immutable The resource’s unique identifier.
    license.id String Required Immutable The active license associated with this environment. This property is required only if your organization has more than one active license.
    name String Required Mutable The environment name, which must be provided and must be unique within an organization.
    organization.id String Optional Immutable The organization resource’s unique identifier associated with the environment.
    region String Required Immutable The region in which this environment will be used. The value is set when the environment is created and cannot be updated. Options are "NA", "CA", "EU", "AU", or "AP".
    softDeletedAt Date N/A Read-only The time the Production environment was set to the DELETE_PENDING status. When a soft-deleted environment is restored, this value is cleared.
    status String Optional* Mutable The status of an environment. (*Required for the Update Environment Status request.) This can be: null, ACTIVE and DELETE_PENDING (soft-delete). The maximum number of Production environments that can be in the DELETE_PENDING state is set to 100.
    type String Required Mutable The type of environment to use. Options are PRODUCTION and SANDBOX.
    updatedAt Date N/A Read-only The time the environment was last updated.

    Filtering data

    GET requests that return environment resources support SCIM filtering expressions. The query filter can be appended to the request URL to fine-tune the response data. For example, the following filter returns only the environments in which the name attribute value starts with the letter "S":

    https://api.pingone.com/v1/environments?filter=name%20sw%20%22S%22

    These SCIM operators can be applied to the following attributes:

    • sw (starts with)

      Supported attributes: name

    • eq (equal to)

      Supported attributes: id, organization.id, license.id, status

    • and (logical AND)

      Supported attributes: Used to connect multiple filters on any attribute.

    For more information about SCIM syntax and operators, see Conventions.

    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.

    Early Access Features

    You can easily choose to add PingOne early access features to an environment using a single request to opt-in or opt-out of a selected feature or features. This enables you to try out new PingOne capabilities prior to release in a sandbox or development environment. You also have the opportunity to let us know whether the new features adequately address the needs of your organization.

    You can choose to:

    • Opt-in or opt-out (the default) to an early access feature or features for a specified environment.
    • Opt-out of a early access feature or features to which you'd previously chosen to opt-in.
    • Opt-in to an early access feature or features for an environment in which the prior existing feature or features also exist. The early access features will not overwrite an existing feature, and will be identified as early access. [?? True?]

    All opt-in and opt-out events are available in the PingOne audit log.

    The API interfaces for the Early Access service are: Read Early Access Features and Update Early Access Features.

    Early Access Features data model

    Property Type Required? Mutable? Description
    name String Required Immutable The name of the early access feature.
    description String Optional Mutable The description of the early access feature.
    segmentKey String Required Immutable The UUID of the early access feature.
    value Boolean Required Mutable The opt-in or opt-out designation. If true you're indicating to opt-in to the early access feature. Defaults to false.

    Read Early Access Features

    Update Early Access Features

    Create Environment

    Read All Environments

    Read One Environment

    Update Environment Status

    Update Environment

    Update Environment Type

    Delete Environment

    Flow Policies

    The flow policies endpoint identifies the DaVinci flow policy resources defined in the specified environment. It provides operations to list all flow policies in the environment or get one flow policy specified by its flow policy ID in the request URL.

    Flow policies are associated with DaVinci applications. A flow policy can have one or more DaVinci-defined flows associated with it.

    Flow policies data model

    Property Type Required? Mutable? Description
    application Object Required Read only An object that specifies the application information associated with the flow policy resource.
    application.id String Required Read only The unique identifier of the application resource associated with the flow policy.
    application.name String Required Read only The name of the application resource associated with the flow policy.
    enabled Boolean Required Read only A boolean that specifies whether the flow policy is enabled.
    environment.id String Required Read only The environment resource's unique identifier associated with the flow policy.
    id String Required Read only The flow policy resource's unique identifier.
    name String Required Read only The flow policy resource name.
    trigger Object Optional Mutable An object that specifies the predefined trigger that can initiate the flow.
    trigger.type String Required Mutable A string that specifies the trigger type. This property is required if the trigger property is set. Options include AUTHENTICATION.

    Response codes

    Code Message
    200 Successful operation.
    400 The request could not be completed.
    404 The requested resource was not found.

    Read All Flow Policies

    Read One Flow Policy

    Forms

    The forms API, which supports the form builder interface in the PingOne Admin Console, provides tools for administrators to create custom forms presented to users during the authentication workflow. This capability allows administrators to:

    • Define the interactive fields and the corresponding data to be collected during a registration or sign-on flow, which could include text inputs, checkboxes, dropdowns, and radio buttons.

    • Define the user experience that they want to deliver to the customer, such as field ordering, labeling, control over input validation and error feedback, and support for contextual or formatting items such as text (headers, explanatory text), and dividers.

    The supported CUSTOM form type gives you the flexibility to create custom forms without having to write HTML. This type also allows the form to be built with fields that do not map specifically to PingOne directory attributes. You can create forms for registration, password reset, password recovery, and many other use cases.

    Translatable keys

    You can add translatable keys for any user-facing text in your forms, including the input field labels, button labels, and rich text. After adding these keys, the text can be translated based on the end user's browser settings for preferred languages.

    Forms data model

    Property Type Required? Mutable? Description
    created Date N/A Read-only The date the resouce was created (ISO-8061 format).
    category String Required Mutable A string that specifies the type of form. Options are CUSTOM. The CUSTOM form type allows the form to be built with fields that do not map specifically to the PingOne directory attributes.
    cols Integer Optional Mutable An integer that specifies the number of columns in the form (min = 1; max = 4).
    components Object Required Mutable An object that specifies the form configuration elements.
    description String Optional Mutable A string that specifies the description of the population.
    environment.id String N/A Read-only A string that specifies the environment’s unique identifier.
    fieldTypes Object Optional Read-only A read-only object that specifies the list of the FormField types in the form. Options are TEXT, PASSWORD, PASSWORD_VERIFY, RADIO, CHECKBOX, DROPDOWN, COMBOBOX, DIVIDER, EMPTY_FIELD, TEXTBLOB (Deprecated), SLATE_TEXTBLOB, SUBMIT_BUTTON, ERROR_DISPLAY, FLOW_LINK, FLOW_BUTTON, SOCIAL_LOGIN_BUTTON, and RECAPTCHA_V2.
    id String N/A Read-only A string that specifies the resource’s unique identifier.
    languageBundle Object Optional Mutable An object that provides a map of i18n keys to their translations. This object includes both the keys and their default translations. The PingOne language management service finds this object, and creates the new keys for translation for this form.
    markOptional Boolean Required Mutable A boolean that specifies whether optional fields are highlighted in the rendered form.
    markRequired Boolean Required Mutable A boolean that specifies whether required fields are highlighted in the rendered form.
    modified Date N/A Read-only The time the resource was last updated.
    name String Required Mutable A string that specifies the form name, which must be provided and must be unique within an environment.
    showPasswordRequirements Boolean Optional Mutable A boolean that specifies whether to return the password requirements during a DaVinci flow. A form with a new password field does not show the password policy information automatically in the response. To return the password policy information, the value of this property must be set to true.
    translationMethod String Optional Mutable A string that specifies how to translate the text strings in the form. Options are TRANSLATE, DEFAULT_VALUE, and KEY.

    Form components data model

    Property Type Required? Mutable? Description
    fields Object Required Mutable A list of form fields that specifies the form fields that make up the form.

    FormField data model

    • FormElement represents a FormField of types TEXT, PASSWORD, RADIO, CHECKBOX, DROPDOWN.
    • FormItem represents a FormField of types DIVIDER, PARAGRAPH, EMPTY_FIELD, ERROR_DISPLAY.
    • FormElementPasswordVerify represents a FormField of type PASSWORD_VERIFY.
    • FormSubmit represents a FormField of type SUBMIT_BUTTON.
    • FormFlowLink represents FormField of type FLOW_LINK.
    • FormFlowButton represents a FormField of type FLOW_BUTTON.
    • FormRecaptchaV2 represents a FormField of type RECAPTCHA_V2.
    • FormSocialLoginButton repesents a FormField of type SOCIAL_LOGIN_BUTTON.
    Property Type Required? Mutable? Description
    position Object Required Mutable An object containing field position information.
    position.col Integer Required Mutable An integer that specifies the number of columns (min = 1; max = 4).
    position.row Integer Required Mutable An integer that specifies the number of rows (maximum number is 50).
    position.width Integer Optional Mutable An integer that specifies the width of the field (in percentage).
    type String Required Mutable A string that specifies the type of the field. Options are TEXT, PASSWORD, PASSWORD_VERIFY, RADIO, CHECKBOX, DROPDOWN, COMBOBOX, DIVIDER, EMPTY_FIELD, TEXTBLOB (Deprecated), SLATE_TEXTBLOB, SUBMIT_BUTTON, ERROR_DISPLAY, FLOW_LINK, FLOW_BUTTON, SOCIAL_LOGIN_BUTTON, and RECAPTCHA_V2.
    key String Required Mutable A string that specifies an identifier for the field component.
    label Object Required Mutable A nested JSON structure that is designed to store a series of text and translatable keys.

    FormElement data model

    Property Type Required? Mutable? Description
    attributeDisabled Boolean Optional Read-only A boolean that specifies whether the linked directory attribute is disabled.
    key String Required Mutable A string that specifies an identifier for the field component.
    labelMode String Optional Mutable A string that specifies how the field is rendered. Options are DEFAULT and FLOAT.
    layout String Optional Mutable A string that specifies layout attributes for radio button and checkbox fields. Options are HORIZONTAL or VERTICAL. This is a required property when the type is RADIO or CHECKBOX.
    options Array[] Optional Mutable An array of strings that specifies the unique list of options. This is a required property when the type is RADIO, CHECKBOX, or DROPDOWN.
    required Boolean Required Mutable A boolean that specifies whether the field is required.
    validation Object Optional Mutable An object containing validation data for the field. This is a required property when the type is TEXT.
    validation.regex String Optional Mutable A string that specifies a validation regular expression. The expression must be a valid regular expression string. This is a required property when the validation type is CUSTOM.
    validation.type String Optional Mutable A string that specifies the validation type. Options are NONE and CUSTOM. This is a required property when the field type is TEXT.
    validation.errorMessage String Optional Mutable A string that specifies the error message to be displayed when the field validation fails.
    otherOptionEnabled Boolean Optional Mutable A boolean that specifies whether the end user can type an entry that is not in a predefined list.
    otherOptionKey String Optional Mutable A string that specifies whether the form identifies that the choice is a custom choice not from a predefined list.
    otherOptionlabel String Optional Mutable A string that specifies the label for a custom or "other" choice in a list.
    otherOptionInputlabel String Optional Mutable A string that specifies the label for the other option in drop-down controls.
    otherOptionAttributeDisabled Boolean Optional Mutable A boolean that specifies whether the directory attribute option is disabled. Set to true if it references a PingOne directory attribute.

    FormElementOption data model

    Property Type Required? Mutable? Description
    label String Required Mutable A string that specifies the label shown to the end user for this option.
    value String Required Mutable A string that specifies the value of the field if this option is selected.

    FormItem data model

    Property Type Required? Mutable? Description
    content String Optional Mutable A string that specifies the field content.

    FormElementPasswordVerify data model

    The FormElementPasswordVerify object is an extension of FormElement and contains all of the same fields in FormElement as well as those listed below.

    Property Type Required? Mutable? Description
    labelPasswordVerify String Optional Mutable A string that when a second field for verifies password is used, this poperty specifies the field label for that verify field.

    FormSubmit and FormFlowButton data model

    Property Type Required? Mutable? Description
    key String Required Mutable A string that specifies an identifier for the field component.
    label String Required Mutable A string that specifies the button label.
    styles.width Integer Optional Mutable An integer that specifies the button width. Set as a percentage.
    styles.alignment String Optional Mutable A string that specifies the button alignment. Options are LEFT, RIGHT, and CENTER.
    styles.backgroundColor String Optional Mutable A string that specifies the button background color. The value must be a valid hexadecimal color.
    styles.textColor String Optional Mutable A string that specifies the button text color. The value must be a valid hexadecimal color.
    styles.borderColor String Optional Mutable A string that specifies the button border color. The value must be a valid hexadecimal color.
    styles.enabled Boolean Optional Mutable A boolean that specifies whether the button is enabled.

    FormFlowLink data model

    Property Type Required? Mutable? Description
    key String Required Mutable A string that specifies an identifier for the field component.
    label String Required Mutable A string that specifies the link label.
    styles.horizontalAlignment String Optional Mutable A string that specifies the link alignment. Options are LEFT, RIGHT, and CENTER.
    styles.textColor String Optional Mutable A string that specifies the link text color.
    styles.enabled Boolean Optional Mutable A boolean that specifies whether the link is enabled.

    FormReCAPTCHA V2 data model

    Property Type Required? Mutable? Description
    key String Required Mutable A string that specifies an identifier for the field component.
    size String Required Mutable A string that specifies the reCAPTCHA size. Options are NORMAL and COMPACT.
    theme String Required Mutable A string that specifies the reCAPTCHA theme. Options are LIGHT and DARK.
    alignment String Required Mutable A string that specifies the reCAPTCHA alignment. Options are LEFT, RIGHT, and CENTER.

    FormSocialLoginButton data model

    Property Type Required? Mutable? Description
    label String Required Mutable A string that specifies the social login button label.
    styles.alignment String Optional Mutable A string that specifies the social login button alignment. Options are LEFT, RIGHT, and CENTER.
    styles.textColor String Optional Mutable A string that specifies the social login button text color.
    styles.enabled Boolean Optional Mutable A boolean that specifies whether the social login button is enabled.
    styles.width Integer Optional Mutable An integer that specifies the button width. Set as a percentage.
    idpType String Required Mutable A string that specifies the external identity provider type. Options are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, and SAML.
    idpName String Required Mutable A string that specifies the external identity provider name.
    idpId String Required Mutable A string that specifies the external identity provider's ID.
    idpEnabled Boolean Required Mutable A boolean that specifies whether the external identity provider is enabled.

    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.

    Create Custom Form

    Read One Form

    Read Forms

    Update Form

    Delete One Form

    Forms Recaptcha

    The Recaptcha configuration API provides support for a Recaptcha V2 field in a form definition. It includes operations to read, update, and delete the environment's Recaptcha configuration.

    Recaptcha V2 data model

    Property Description
    created The time the configuration was created.
    environment.id A string that specifies the environment's unique identifier.
    modified The time the configuration was last updated.
    siteKey A string that specifies the public site key for the Recaptcha configuration provided by Google. This is a required property.
    secretKey A string that specifies the confidential secret key for the Recaptcha configuration provided by Google. This is a required property.

    Response codes

    Code Message
    200 Successful operation.
    204 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.

    Read Recaptcha Configuration

    Update Recaptcha Configuration

    Delete Recaptcha Configuration

    Gateway Management

    A PingOne gateway connects resources in a remote security domain (such as, an on-premises datacenter or a hosted private cloud) with a PingOne environment. Gateways give you the ability to tie your organizations on-premise resources into PingOne.

    You can create gateway resources in PingOne, and then manage the gateways from PingOne. There are gateway endpoints to return information about the health of the gateway, errors generated by the gateway, and gateway instance runtime metrics.

    Once you've created the gateway in PingOne, users in the remote directory are created through the gateway as PingOne users the first time they sign on to PingOne.

    The following resources are managed through the PingOne Gateway service:

    Gateways and gateway instances

    To create the communication linkage between PingOne and your remote directory, you need to deploy software in your infrastructure that can communicate with both PingOne and your remote directory. There are two parts to successfully getting the software in place:

    1. Configuring a gateway in PingOne.

    2. Running a Docker instance that's configured for the PingOne gateway in your on-premise or cloud-hosted environment. The running Docker container is known as a gateway instance. For testing purposes, a single gateway instance is sufficient, but for production deployments, multiple gateway instances should be deployed for high availability.

    Gateway credentials

    The gateway instance running within your infrastructure authenticates with PingOne through gateway credentials. Gateway credentials are supplied to a gateway instance at startup. A gateway credential is like a password, so it needs to be protected. For security reasons, PingOne doesn't store the gateway credentials that you've generated, though you can always create new gateway credentials in the PingOne admin console. Multiple gateway instances can use the same gateway credentials. For more information about gateway credentials, see Gateway Credentials.

    Gateway role assignments

    If you're using PingFederate, you can manage gateway access to PingOne resources using PingOne's role-based access control (RBAC) model to assign a role to the gateway. See Gateway Role Assignments for more information.

    Use Cases

    Gateway base data model

    Property Type Required? Mutable? Description
    credentials Object[] Optional Mutable An array of objects that specifies the list of gateway credentials. The objects have information about the credential and these are the credentials that gateway instances use or could be actively using. The maximum number of credentials is five. If there are no gateway credentials specified for a gateway, this property is not present.
    description String Optional Mutable Specifies the description of the resource.
    _embedded.instances Object[] Optional Mutable An array of gateway instances. Active instances are returned for the gateway resource when expand=instances is specified in the request.
    enabled Boolean Required Mutable Indicates whether the gateway is enabled.
    environment.id String Required Immutable The unique identifier for the environment associated with the resource.
    id String Required Immutable The resource’s unique identifier.
    name String Required Mutable The resource name, which must be provided and must be unique within an environment. Valid characters are any Unicode letter, mark, numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
    supportedVersions Object Optional Mutable The LDAP gateway versions associated with this gateway resource. This information is returned on a GET {{apiPath}}/environments/{{envID}}/gateways request, and it is used to trigger alerts if the gateway tries to connect with an unsupported version (or a version that is not the latest or recommended version).
    supportedVersions.version String Optional Mutable The gateway version number.
    supportedVersions.image String Optional Mutable Identifies the gateway image path.
    supportedVersions.recommended Boolean Optional Mutable Indicates whether this is the recommended LDAP gateway version.
    supportedVersions.latest Boolean Optional Mutable Indicates whether this is the latest LDAP gateway version.
    type String Required Immutable The type of gateway resource. Options are LDAP, API_GATEWAY_INTEGRATION, PING_FEDERATE, and RADIUS.

    Gateway LDAP data model

    Property Type Required? Mutable? Description
    bindDN String Required Mutable The distinguished name information to bind to the LDAP database (for example, uid=pingone,dc=example,dc=com).
    bindPassword String Required Mutable The Bind password for the LDAP database.
    connectionSecurity String Optional Mutable The connection security type. Options are None, TLS, and StartTLS. The default value is None.
    followReferrals Boolean Optional Mutable Defaults to false if the payload does not contain the property. If set to true, PingOne sends LDAP queries per referrals it receives from the LDAP servers.
    kerberos Object Optional Mutable Contains the Kerberos authentication settings. Set this to null to disable Kerberos authentication.
    kerberos.serviceAccountPassword String Optional Mutable The password for the Kerberos service account.
    kerberos.serviceAccountUserPrincipalName String Required Mutable The Kerberos service account user principal name (for example, "username@domain.com").
    kerberos.minutesToRetainPreviousCredentials Integer Optional Mutable The number of minutes for which the previous credentials are persisted.
    serversHostAndPort String[] Required Mutable The LDAP server host name and port number (for example, ["ds1.example.com:389", "ds2.example.com:389"]).
    userTypes Object[] Required Mutable The userTypes properties for the users to be provisioned in PingOne. userTypes specifies which user properties in PingOne correspond to the user properties in an external LDAP directory. You can use an LDAP browser to view the user properties in the external LDAP directory.
    userTypes.allowPasswordChanges Boolean Optional Mutable Defaults to false if this property isn't specified in the request. If false, the user cannot change the password in the remote LDAP directory. In this case, operations for forgotten passwords or resetting of passwords are not available to a user referencing this gateway.
    userTypes.updateUserOnSuccessfulAuthentication Boolean Optional Mutable If set to true, when users sign on through an LDAP Gateway client, user attributes are updated based on responses from the LDAP server. Defaults to false if this property isn't specified in the request.
    userTypes.id UUID Required Mutable Identifies the user type. This correlates to the password.external.gateway.userType.id User property.
    userTypes.name String Required Mutable The name of the user type.
    userTypes.newUserLookup Object Optional Mutable The configurations for initially authenticating new users who will be migrated to PingOne. Note: If there are multiple users having the same user name, only the first user processed is provisioned.
    userTypes.newUserLookup.attributeMappings Object[] Required Mutable A list of objects supplying a mapping of PingOne attributes to external LDAP attributes. One of the entries must be a mapping for "username”. This is required for the PingOne user schema.
    userTypes.newUserLookup.attributeMappings.name String Required Mutable The PingOne username attribute. See Users properties for the complete list of PingOne user attributes.
    userTypes.newUserLookup.attributeMappings.value Object Required Mutable A placeholder reference to the corresponding external LDAP attribute for name.
    userTypes.newUserLookup.ldapFilterPattern String Optional Mutable The LDAP user search filter to use to match users against the entered user identifier at login. For example, (((uid=${identifier})(mail=${identifier})). Alternatively, this can be a search against the user directory.
    userTypes.newUserLookup.population String Optional Mutable The PingOne population to use to create user entries during lookup.
    userTypes.newUserLookup.population.id UUID Optional Immutable The ID of the population to use to create user entries during lookup.
    userTypes.orderedCorrelationAttributes Object[] Optional Mutable A map of name-value entries used to persist the external LDAP directory attributes.
    userTypes.passwordAuthority String Required Mutable This can be either PING_ONE or LDAP. If set to PING_ONE, PingOne authenticates with the external directory initially, then PingOne authenticates all subsequent sign-ons.
    userTypes.searchBaseDn String Optional Mutable The LDAP base domain name (DN) for this user type.
    validateTlsCertificates Boolean Optional Mutable Indicates whether or not to trust all SSL certificates (defaults to true). If this value is false, TLS certificates are not validated. When the value is set to true, only certificates that are signed by the default JVM CAs, or the CA certs that the customer has uploaded to the certificate service are trusted.
    vendor String Required Immutable The LDAP vendor. Options are PingDirectory, Microsoft Active Directory, Oracle Directory Server Enterprise Edition, Oracle Unified Directory, CA Directory, OpenDJ Directory Server, IBM (Tivoli) Security Directory Server, and LDAPv3-compliant Directory Server.

    Gateway RADIUS data model

    Property Type Required? Mutable? Description
    davinci.policy.id String Required Mutable The ID of the Davinci flow policy to use.
    defaultSharedSecret String Optional Mutable Value to use for the shared secret if the shared secret is not provided for one or more of the RADIUS clients specified.
    networkPolicyServer Object Optional Mutable If specified, the RADIUS gateway authenticates using the MS-CHAP v2 or EAP-MSCHAP v2 protocol.
    networkPolicyServer.ip String Required Mutable The IP address of the Network Policy Server (NPS).
    networkPolicyServer.port Integer Required Mutable The port number of the NPS.
    radiusClients Object[] Required Mutable Collection of RADIUS clients.
    radiusClients.blastRadiusMitigation Object Optional Mutable The blastRadiusMitigation object contains two optional fields that can be used to block Blast RADIUS attacks. Since these two options use different approaches to deal with the same issue, you should not set more than one of them to true. If both are set to true, an error is returned.
    radiusClients.blastRadiusMitigation.requireMsgAuth Boolean Optional Mutable Set requireMsgAuth to true to require that all requests from the client include the Message-Authenticator attribute. Any requests without the attribute will be ignored.
    radiusClients.blastRadiusMitigation.limitProxyState Boolean Optional Mutable For older clients that don't support sending the Message-Authenticator attribute, you can set limitProxyState to true. This instructs the gateway to ignore requests that don't contain the Message-Authenticator attribute but contain the Proxy-State attribute.
    radiusClients.ip String Required Mutable The IP of the RADIUS client.
    radiusClients.sharedSecret String Optional Mutable The shared secret for the RADIUS client. If this value is not provided, the shared secret specified with defaultSharedSecret is used. If you are not providing a shared secret for the client, leave out sharedSecret or set it to null.

    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.
    404 The requested resource was not found.

    Gateways

    Gateway resources provide the communication linkage between PingOne and your remote directory. Use these requests to manage gateway resources, including the request body properties required to create a PingFederate connection.

    Create LDAP Gateway

    Create PingFederate Connection

    Create RADIUS Gateway

    Create API Gateway Integration

    Read All Gateways

    Read One Gateway

    Update LDAP Gateway

    Update RADIUS Gateway

    Delete Gateway

    Gateway Credentials

    The gateway instance running within your infrastructure authenticates with PingOne through a gateway credential. The examples that follow show common actions to create and manage gateway credentials.

    You need the Environment Admin role to perform operations on gateway entities.

    Gateway credentials data model

    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The date the credential was created in Coordinated Universal Time (UTC).
    id String N/A Read-only The auto-generated ID for this credential. This is the JWT's jti claim.
    lastUsedAt Date N/A Read-only The date the credential was last used in UTC.
    token String N/A Read-only The signed JWT for the gateway credential. This property is present only when the gateway credential is created.
    Gateway credentials token claims

    The gateway credential includes the following claims:

    Claim Type Description
    aud String The names of resources that this token is intended for (for example, https://api.pingone.com).
    authUrl String The authorization server URL (for example, https://auth.pingone.com).
    consoleUrl String The admin console URL (for example, https://console.pingone.com).
    environmentId String The environment ID of the authenticated user or application.
    environmentName String The name of the PingOne environment.
    gatewayId String The PingOne gateway ID.
    gatewayName String The name of the PingOne gateway.
    gatewayType String The PingOne gateway type. Options are LDAP, API_GATEWAY_INTEGRATION, and PING_FEDERATE.
    iat Integer The timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519.
    iss String The per-environment issue URI: wss://gateways.pingone.com.
    jti String The UUID for the token.
    organizationId String The PingOne organization ID of the authenticated user or application.
    organizationName String The name of the PingOne organization.
    region String The target region's name.
    targetClusterEnvironment String The name of the PingOne target cluster environment.
    targetGeography String The target's region. Options are "NA", "CA", "EU", or "AP".
    Response codes
    Code Message
    201 Successfully created.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Create Gateway Credentials

    Read All Gateway Credentials

    Read One Gateway Credential

    Delete Gateway Credentials

    Gateway Instances

    Use these data models and requests to find and manage gateway instances resources.

    Gateway instance view data model

    A gateway instance represents a single Docker container that runs on-premise with the configuration for a gateway. PingOne provides a read-only view of the gateway's status and identifying information.

    Property Type Required? Mutable? Description
    connected Boolean N/A Read-only Indicates whether or not the gateway instance has one or more connections.
    credential.id String N/A Read-only The ID of the credential used by the gateway instance to create a websocket connection. The ID of the credential is the gateway credential's jti claim.
    currentErrors String[] N/A Read-only The messages that are maintained by the gateway instance.
    gateway.id String Required Immutable The UUID for the gateway.
    healthStatus Enum N/A Read-only Indicates whether or not the gateway is in a healthy state. Options are HEALTHY, DEGRADED, UNHEALTHY.
    hostname String N/A Read-only The hostname of the container running in the customer’s infrastructure.
    id String Required Immutable The instance ID of the gateway. The gateway instance ID is created by the gateway when it starts up.
    initializedAt Date N/A Read-only When the gateway was initialized (when the first connect to PingOne was made).
    lastReportedAt Date N/A Read-only The last reported timestamp, heartbeat, or other message.
    version Object N/A Read-only Contains the version of the gateway running for the instance.
    version.versionNumber String N//A Read-only The version number of the gateway running for the instance.
    version.updateStatus Enum N/A Read-only One of the following values:
    • AT_LATEST: The gateway instance's version is at or after the supported version marked latest.
    • UPGRADE_AVAILABLE: The gateway instance's version is at the supported version that is marked recommended but there is a later supported version marked recommended.
    • UPGRADE_RECOMMENDED: The gateway instance's version is at a known version but the version is not marked as recommended or latest. The version has greater than 30 days support.
    • UPGRADE_REQUIRED: The gateway instance's version is at a known version but the version is not marked as recommended or latest. The version has support ending within the next month.
    • NOT_SUPPORTED: The gateway instance's version is not known or supported.
    Gateway LDAP instance data model
    Property Type Required? Mutable? Description
    busyPercentage Integer N/A Read-only The gateway instance's busy percentage. When this percentage is high, then more instances should be added.
    operationsPerSecond Integer N/A Read-only The recent throughput of the gateway instance.
    responseTimeMillis Integer N/A Read-only The processing time of the gateway instance in milliseconds.
    Response codes
    Code Message
    200 Successful operation.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Read All Gateway Instances

    Read One Gateway Instance

    Gateway Role Assignments

    The gateway role assignments service provides functionality to assign role assignments to a gateway so that the gateway can access the PingOne services it needs. Only gateway resources with a type property value of PING_FEDERATE can have assigned built-in roles.

    Use these data models and requests to manage gateway role assignments. For more information, see Roles.

    Role assignment scopes can be:

    • Organization

    • Environment

    • Population

    • Application

    Gateway role assignments data model
    Property Type Required? Mutable? Description
    gateway.id String Required Immutable The UUID for the gateway.
    environment.id String Required Immutable The environment associated with the gateway.
    id String N/A Read-only The gateway role assignment ID.
    role.id String Required Immutable The role ID.
    scope.id String Required Immutable The role assignment scope ID. When this is an application ID, because an application ID is guarenteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.
    scope.type String Required Immutable The type of resource defining the scope of the Role assignment. Options are ORGANIZATION, ENVIRONMENT, and POPULATION, APPLICATION.
    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.
    404 The requested resource was not found.

    Create Gateway Role Assignments

    Read Gateway Role Assignments

    Read One Gateway Role Assignment

    Delete Gateway Role Assignment

    Images

    Use the Images service to associate a custom image with an environment:

    • For use with logos for the Branding service.
    • For icons displayed in the PingOne dock.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    images IMAGE.CREATED
    images IMAGE.ACTIVATED
    images IMAGE.DELETED

    Images data model

    Property Type Required? Mutable? Description
    createdAt String N/A Read-only The time the resource was created.
    environment.id String N/A Read-only The environment resource’s unique identifier.
    id String N/A Read-only The resource’s unique identifier.
    targets.height String Required Mutable The height of the image (in pixels).
    targets.href String Optional Mutable The URL or fully qualified path to the image source file.
    targets.id String Optional Mutable The UUID of the target image.
    targets.type String Optional Mutable The type of format used for the image. Options are jpg, png, and gif.
    targets.width String Optional Mutable The width of the image (in pixels).

    Response codes

    Code Message
    200 Successful operation.
    201 Successfully created.
    401 You do not have access to this resource.
    403 You do not have permissions or are not licensed to make this request.

    Create Image

    Read Image

    Delete Image

    Language Management

    The Languages service supplies operations to create, read, update, and delete languages resources within a specified environment. Language resources are used by the PingOne UI (such as, terms-of-service agreements, and notifications services) to present UI elements in a designated language.

    For more information about the Languages service, see Languages in the PingOne Admin Guide.

    The Languages service is comprised of:

    Languages

    The languages endpoints enable you to create, read, update and delete language resources. For more information see Languages.

    Language Localization Status

    The status endpoints enable you to create, read, update and delete language localization status resources. For more information see Language Localization Status.

    Language Translations

    The translations endpoints enable you to view the UI string translations for a specified language, and to update localized strings for UI elements in the specified language.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    lang-mgt LANGUAGE.CREATED
    notifications LOCALIZATION_STATUS.UPDATED
    agreements LOCALIZATION_STATUS.CREATED
    agreements LOCALIZATION_STATUS.UPDATED
    agreements LOCALIZATION_STATUS.DELETED

    Languages

    There are 239 language codes in the ISO standard language code table. This service supports a maximum of fourteen (14) languages resources at one time. The languages service supports the following input and output data model properties for languages resources.

    Languages input data model
    Property Type Required? Mutable? Description
    default Boolean Required Mutable Specifies whether this language is the default for the environment. This property value must be set to false when creating a language resource. It can be set to true only after the language is enabled and after the localization of an agreement resource is complete when agreements are used for the environment.
    enabled Boolean Required Mutable Specifies whether this language is enabled for the environment. This property value must be set to false when creating a language.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.
    id String Required Immutable The resource’s unique identifier.
    locale String Required Mutable An ISO standard language code. For more information about standard language codes, see ISO Language Code Table.
    name String Optional Mutable The language name. If omitted, the ISO standard name is used.
    Languages output data model
    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The time the language resource was created.
    customerAdded Boolean Optional Mutable Specifies whether this language was added by a customer administrator.
    default Boolean Required Mutable Specifies whether this language is the default for the environment. This property value must be set to false when creating a language resource. It can be set to true only after the language is enabled and after the localization of an agreement resource is complete when agreements are used for the environment.
    enabled Boolean Required Mutable Specifies whether this language is enabled for the environment. This property value must be set to false when creating a language.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.
    id String Required Immutable The resource’s unique identifier.
    locale String Required Mutable An ISO standard language code. For more information about standard language codes, see ISO Language Code Table.
    name String Optional Mutable The language name. If omitted, the ISO standard name is used.
    updatedAt Date N/A Read-only The time the language resource was last updated.
    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.

    Create Language

    Read Languages

    Read One Language

    Update Language

    Delete Language

    Language Localization Status

    The scope of language localization in PingOne is limited to end-user facing resources such as sign-on screens, registration agreements, notifications, and any other communications with end users. Localization is not applicable to administrator communications.

    The languages service supports the following data model properties for language localization status resources.

    Languages localization status data model
    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The time the language localization status resource was created.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.
    id String Required Immutable The resource’s unique identifier.
    locale.id String Required Immutable The locale ID.
    service String Required Mutable The name of the service associated with this resource.
    updatedAt Date N/A Read-only The time the language localization status resource was last updated.
    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.

    Create Language Localization Status

    Read Language Localization Status

    Read One Language Localization Status

    Update Language Localization Status

    Delete Language Localization Status

    Language Translations

    The translations endpoint supplies operations to view the custom string translations for a specified language, and to update localized strings for UI elements in the specified language.

    The response for a GET request returns the embedded resources that supply UI strings in English, and the associated localized string content in the specified language. Here's a sample of a localized string (in French) for the Cancel button in the flow-ui module used in a UI page:

        "_embedded": {
        "translations": [
            {
                "id": "3e90224d-9036-4d78-badb-65e98f4fc944",
                "key": "flow-ui.button.cancel",
                "shortKey": "button.cancel",
                "referenceText": "Cancel",
                "translatedText": "Annuler"
            },

    PingOne support UI string translations for the following languages:

    Locale Language
    de German
    en English
    es Spanish
    fr French
    fr-CA French (Canadian)
    it Italian
    ja Japanese
    ko Korean
    nl Dutch
    pt Portuguese
    ru Russian
    th Thai
    tr Turkish
    zh Chinese

    Languages translation request data model

    For PUT requests, the following properties are required in the request body.

    Property Type Required? Mutable? Description
    key String Required Mutable A string that specifies the page and name of the interface element to be localized (for example, flow-ui.button.cancel).
    translatedText String Required Mutable A string that specifies the translated string text associated with the interface element.

    Languages translation response data model

    For GET requests, the data model returns the following information about the specified language's localized strings.

    Property Type Description
    translations.id String The translation ID for a specific string.
    translations.key String The page and name of the interface element to be localized (for example, flow-ui.button.cancel).
    translations.shortKey String The interace element only (for example, button.cancel).
    translations.referenceText String The English string text associated with the interface element.
    translations.translatedText String The translated string text associated with the interface element.

    Response codes

    Code Message
    200 Successful operation.
    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.

    Read Translation

    Update Translation

    Licenses

    The Licenses service manages license assignments at the organization level and enforcement of licensing limits at the environment level. Organizations can have multiple licenses, including multiple active licenses. You can use the licenses endpoints to view your organization's licenses, check which licenses are active (or terminated), and check the allowed PingOne platform entitlements supported by the license.

    Each environment is associated with one license only. The property values of the license resource specify the licensing boundaries. The license identifies the organization that owns the license, the licensing package type, and the expiration date for the license. The following entitlements are also defined in the licensing package:

    For environments:

    • Allow or deny production environments
    • Designate the maximum number of environments allowed by the organization
    • Designate the allowed regions

    For users and applications:

    • Set the maximum number of users for the environment

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    licensing LICENSE.CREATED
    licensing LICENSE.UPDATED
    licensing LICENSE.DELETED
    licensing LICENSE.ORGANIZATION.ACTIVE
    licensing LICENSE.ENVIRONMENT.ACTIVE
    licensing LICENSE.REPLACED

    License data model

    Property Type Required? Mutable? Description
    assignedEnvironmentsCount Integer N/A Read-only The total number of environments associated with this license.
    authorize.allowApiAccessManagement Boolean N/A Read-only Indicates whether to enable the PingOne Authorize API access management feature.
    authorize.allowDynamicAuthorization Boolean N/A Read-only Indicates whether to enable the PingOne Authorize dynamic authorization feature.
    beginsAt Date Required Mutable The date and time this license begins.
    environments.allowConnections Boolean Required Mutable Indicates whether the license supports creation of application connections in the specified environment.
    environments.allowCustomDomain Boolean N/A Read-only Indicates whether the license supports creation of a custom domain in the specified environment.
    environments.allowCustomSchema Boolean N/A Read-only Indicates whether the license supports using custom schema attributes in the specified environment.
    environments.allowProduction Boolean N/A Read-only Indicates whether production environments are allowed.
    environments.max Integer N/A Read-only The maximum number of environments allowed.
    environments.regions String N/A Read-only The allowed regions associated with environments. Options are "NA", "CA", "EU", or "AP".
    expiresAt Date Required Mutable The date and time this license expires. TRIAL licenses stop access to PingOne services at expiration. All other licenses trigger an event to send a notification when the license expires but do not block services.
    id String N/A Read-only The license resource’s unique identifier.
    intelligence.allowGeoVelocity Boolean N/A Read-only Indicates whether to use the intelligence geo-velocity feature. For TRIAL (unpaid) licenses, the default value is true. For ADMIN, GLOBAL, RISK, and MFARISK, the default value is true.
    intelligence.allowAnonymousNetworkDetection Boolean N/A Read-only Indicates whether to use the intelligence anonymous network detection feature. For TRIAL (unpaid) licenses, the default value is true. For ADMIN, GLOBAL, RISK, and MFARISK, the default value is true.
    intelligence.allowReputation Boolean N/A Read-only Indicates whether to use the intelligence IP reputation feature. For TRIAL (unpaid) licenses, the default value is true. For ADMIN, GLOBAL, RISK, and MFARISK, the default value is true.
    intelligence.allowDataConsent Boolean N/A Read-only Indicates whether the customer has opted in to allow user and event behavior analytics (UEBA) data collection.
    intelligence.allowRisk Boolean N/A Read-only Indicates whether your license permits you to configure risk features such as sign-on policies that include rules to detect anomalous changes to your locations (such as impossible travel). This capability is supported for TRIAL, RISK, and MFARISK license packages. Note: The sharing of user data to enable our machine-learning engine, which is integral to PingOne Protect, is captured in the license property license.intelligence.allowDataConsent, but it is not set to true by default in any license package. This license capability always requires active consent by the customer before it can be enabled, and if consent is given, then it allows the full scope of intelligence features included in PingOne Protect (and PingOne Protect plus MFA).
    intelligence.allowIntelligenceProtect Boolean N/A Read-only Indicates whether your license permits you to configure protect features. Note: The sharing of user data to enable our machine-learning engine, which is integral to PingOne Protect, is captured in the license property license.intelligence.allowDataConsent, but it is not set to true by default in any license package. This license capability always requires active consent by the customer before it can be enabled, and if consent is given, then it allows the full scope of intelligence features included in PingOne Protect (and PingOne Protect plus MFA).
    intelligence.numberOfProtectTransactions Integer N/A Read-only Indicates the number of protect transactions allowed.
    mfa.allowPushNotification Boolean N/A Read-only Indicates whether push notifications are allowed. For TRIAL (unpaid) licenses, the default value is true. For other license package types, adoption of the feature determines the default value.
    mfa.allowMfaNotificationsOutsideWhitelist Boolean Required Immutable Indicates whether the license supports sending notifications outside of the environment's whitelist.
    mfa.allowFido2Devices Boolean N/A Read-only Indicates whether FIDO2 devices are allowed. For TRIAL (unpaid) licenses, the default value is true. For other license package types, adoption of the feature determines the default value.
    name String Required Mutable A string that specifies a descriptive name for the license. This is a required property in a license name update request. Valid characters consists of any Unicode letter, mark, numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen. The maximum length of a name is 255 characters.
    organization.id String N/A Read-only The organization resource’s unique identifier associated with the license.
    package String Required Mutable A string that specifies the license template on which this license is based. This is a required property. Options are TRIAL, STANDARD, PREMIUM, MFA, RISK, MFARISK, and GLOBAL. These values are not fixed.
    replacesLicense.id String Optional Immutable The license ID of the license that is replaced by this license.
    replacedByLicense.id String Optional Immutable The license ID of the license that replaces this license.
    status String Required Mutable The status of the license. Options are ACTIVE, EXPIRED, and FUTURE.
    terminatesAt Date Optional Mutable The exact date and time when this license terminates access to PingOne services. This attribute can be added to any licensing package.
    users.allowPasswordManagementNotifications Boolean Required Mutable Indicates whether the license supports sending password management notifications.
    users.allowIdentityProviders Boolean N/A Read-only Indicates whether the license supports using external identity providers in the specified environment.
    users.allowMyAccount Boolean N/A Read-only Indicates whether the license supports using My Account capabilities in the specified environment.
    users.allowPasswordManagementNotifications Boolean N/A Read-only Indicates whether the license supports using password management capabilities in the specified environment.
    users.allowPasswordOnlyAuthentication Boolean N/A Read-only Indicates whether the license supports using password only login capabilities in the specified environment.
    users.allowPasswordPolicy Boolean N/A Read-only Indicates whether the license supports using password policies in the specified environment.
    users.allowProvisioning Boolean N/A Read-only Indicates whether the license supports using provisioning capabilities in the specified environment.
    users.allowRoleAssignment Boolean N/A Read-only Indicates whether the license supports role assignments in the specified environment.
    users.users.allowVerificationFlow Boolean N/A Read-only Indicates whether the license supports using verification flows in the specified environment.
    users.allowUpdateSelf Boolean N/A Read-only Indicates whether the license supports allowing users to update their own profile.
    users.entitledToSupport Boolean N/A Read-only Indicates whether the license allows PingOne support.
    users.max Integer N/A Read-only The maximum number of users allowed per environment.
    users.annualActiveIncluded Integer N/A Read-only A soft limit on the number of active identities across all environments on the license per year. This property is not visible if a value is not provided at the time the license is created.
    users.monthlyActiveIncluded Integer N/A Read-only A soft limit on the number of active identities across all environments on the license per month. This property is not visible if a value is not provided at the time the license is created.
    verify.allowPushNotifications Boolean N/A Read-only Indicates whether to enable the PingOne Verify push notifications feature.
    verify.allowDocumentMatch Boolean N/A Read-only Indicates whether to enable the PingOne Verify document matching feature.
    verify.allowFaceMatch Boolean N/A Read-only Indicates whether to enable the PingOne Verify face matching feature.
    verify.allowManualIdInspection Boolean N/A Read-only Indicates whether to enable the PingOne Verify `manual ID inspection feature.
    verify.numberOfDigitalVerifications Integer N/A Read-only The maximum number of digital verifications allowed per environment.
    verify.numberOfUniversalCapture Integer N/A Read-only The maximum number of universal captures allowed per environment.
    verify.numberOfAAMVA Integer N/A Read-only The maximum number of AAMVA allowed per environment.
    verify.numberOfVoiceBiometrics Integer N/A Read-only The maximum number of voice biometrics allowed per environment.

    Response codes

    Code Message
    200 Successful operation.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Read All Licenses

    Read One License

    Read One License Name

    Update One License Name

    Notifications

    The following section provides API reference information about the PingOne platform's notification services:

    • Notifications Templates

      Endpoints to manage notifications templates and email, voice, SMS, and push notifications contents.

    • Notifications Settings

      Endpoints to configure specific notifications settings for an identified environment.

    • Notifications Settings (SMTP)

      Endpoints to configure specific notifications settings for the organization's own SMTP service to send email notifications for each environment, instead of the built-in email service of PingOne.

    • Notifications Policies

      Endpoints to define notification policies to limit the use of SMS/voice and email notifications for pairing and authentication.

    • Phone Delivery Settings

      Endpoints to configure different accounts which could be used for sending an SMS or voice message.

    • Trusted Email Domains

      Endpoints to configure up to 50 trusted email domains for each environment.

    • Trusted Email Addresses

      Endpoints to configure up to 10 trusted email address for an existing trusted email domain.

    • Send Notifications

      Endpoints to send test notifications to a mobile application.

    Notifications Templates

    The templates endpoints manage notifications templates and notifications contents. Each content is based on one specific template. Each template can be associated with multiple contents.

    Each environment has a set of predefined notifications templates it can access. A template represents a specific process flow, for example, device_pairing or strong_authentication, that requires a notification. Each template defines the deliveryMethods (Email, SMS, Voice, WhatsApp, or Push) that it supports. You can read templates with this API, but you cannot create, update, or delete them.

    Notifications templates settings

    Template name ID Description Delivery methods Supported predefined variables Dynamic variables allowed
    Credential Issued credential_issued Users will receive this message when a credential is issued to them SMS, Email, Push credential.name (optional), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Credential Revoked credential_revoked Users will receive this message when a credential they have is revoked SMS, Email, Push credential.name (optional), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Credential Updated credential_updated Users will receive this message when a credential they have is updated SMS, Email, Push credential.name (optional), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Credential Verification Push credential_verification Users' digital wallet will receive this message as a pushed notification of creation of a credential verification session Push None No
    Device pairing device_pairing Users will receive this message to pair their device for strong authentication SMS, Email, Voice, WhatsApp otp (required), user.username (optional), user.name.given (optional), user.name.family (optional), current-year (optional). For WhatsApp content, only otp is supported. Yes (for delivery methods other than WhatsApp)
    Digital Wallet Pairing digital_wallet_pairing Users will receive this message to setup and pair a digital wallet. SMS, Email app.open.url (required), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Email Address Verification (Admin) email_verification_admin Admins will receive this message to verify their email address Email code (required), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Email Address Verification (User) email_verification_user Users will receive this message to verify their email address Email code (required), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Email and Phone Verification for Verify email_phone_verification Users will receive this message to verify their phone number or email address for a verify transaction SMS, Email otp (required), user.username (optional), user.name.given (optional), user.name.family (optional) No
    General general Use this multi-purpose template to create custom notifications SMS, Email, Voice user.username (optional), user.name.given (optional), user.name.family (optional), current-year (optional) Yes
    ID Verification id_verification Users will receive this message to verify their email address SMS, Email app.open.url (required), user.username (optional), user.name.given (optional), user.name.family (optional) No
    New Device Paired new_device_paired When a new device is paired, a notification will be sent to the user that a device has been registered to their account SMS, Email device.name (required), org.name (optional), report.fraud (optional) - inserts a link for reporting fraudulent pairing attempts No
    Password Recovery recovery_code_template Users who need to reset their password will receive this message Email code.value (required), user.username (optional), user.name.given (optional), user.name.family (optional) No
    Strong Authentication strong_authentication Users will receive this message for strong authentication SMS, Email, Push, Voice, WhatsApp otp (required for SMS, Email, Voice), user.username (optional), user.name.given (optional), user.name.family (optional), current-year (optional). For WhatsApp content, only otp is supported. Yes (for delivery methods other than WhatsApp)
    Transaction transaction Users will receive this message for transaction approval SMS, Email, Push, Voice otp (required for SMS, Email, Voice), user.username (optional), user.name.given (optional), user.name.family (optional) Yes
    Verification Code verification_code_template Users will receive this message to verify their email address Email code.value (required), user.username (optional), user.name.given (optional), user.name.family (optional) No

    A content defines one message text choice for a notification. Each content is always associated with one template and has one deliveryMethod and one locale. Each template comes with one predefined default content for each of its supported deliveryMethods. You cannot delete or update the default contents with this API. However, you can create custom contents for a template (up to 1000 custom contents per template). To create custom contents, see Creating custom contents.

    Notification templates assignment and initiation

    A notification template is defined for a specifc process flow to convey information about the process flow to its user. Typically, a service provides a request that can assign a specific variant or a specific locale or both (for more information on variants and locales, see Creating custom contents) for a notification used by its process flow. For example, Create Credential Issuance Rule has a notification.template object that can set the notification template variant and locale for notifications sent when a user credential is created, updated, or revoked through Apply Credential Issuance Rule Staged Changes or its automated equivalent.

    In this table, the notification template in Template name is assigned a variant or locale in the request in Defined by and the supported process flow begins with the request in Initiated by.

    Template name Defined by Initiated by
    credential_issued Create Credential Issuance Rule or Update Credential Issuance Rule Apply Credential Issuance Rule Staged Changes or its automated equivalent when the issuance rule's automation.issue is PERIODIC.
    credential_issued Create a User Credential Create a User Credential
    credential_revoked Create Credential Issuance Rule or Update Credential Issuance Rule Apply Credential Issuance Rule Staged Changes or its automated equivalent when the issuance rule's automation.revoke is PERIODIC.
    credential_updated Create Credential Issuance Rule or Update Credential Issuance Rule Apply Credential Issuance Rule Staged Changes or its automated equivalent when the issuance rule's automation.update is PERIODIC.
    credential_updated Update a User Credential Update a User Credential
    credential_verification Create Credential Verification Session (NATIVE - Push Notification) Create Credential Verification Session (NATIVE - Push Notification)
    device_pairing Defined by the flow status. Initiated by the DEVICE_SELECTION_REQUIRED flow status.
    digital_wallet_pairing Create Digital Wallet Create Digital Wallet
    email_phone_verification Create Verify Policy or Update Verify Policy, but cannot define a locale. Create Verify Transaction
    email_verification_admin Defined by the flow status. Initiated by the VERIFICATION_REQUIRED flow status. See Send Email Verification (Code).
    email_verification_user Defined by the flow status. Initiated by the VERIFICATION_REQUIRED flow status. See Send Email Verification (Code).
    general Defined by the flow status. Initiated by a flow status that sends a one-time passcode through email, SMS, or voice.
    id_verification Cannot define a variant or locale Create Verify Transaction
    new_device_paired Add the notifications property to the Create MFA User Device request. See MFA Devices.
    recovery_code_template Defined by the flow status. Initiated by the RECOVERY_CODE_REQUIRED flow status. The user initiated a password.forgot flow action and a recovery code must be sent.
    strong_authentication Defined by the flow status. Initiated by an MFA flow status that sends a push notification on mobile apps or a one-time passcode through email, SMS, or voice.
    transaction Defined by the pi.template property in an authorize request's request property JWT. Initiated by the authorize request. See Authorize (Transaction Approval).
    verification_code_template Defined by the flow status. Initiated by the VERIFICATION_REQUIRED flow status. See Register User.

    Runtime logic for content selection

    Each content, whether default or custom, is associated with one template, one deliveryMethod, one locale, and optionally, one variant (for more information on variants, see Creating custom contents). When a request for content is executed at runtime, it includes a template, deliveryMethod, and optionally a variant.

    When determining the language to use for a notification, PingOne uses the following logic:

    • The preferred language is determined by:

      1. Checking first if locale is specified in the API request, for example, in the notification.template.locale property for POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices.
      2. If locale was not specified in the request, the preferred language that was set for the user in PingOne is used.
      3. If there is no preferred language set for the user in PingOne, the Accept-Language header in the request is checked.
      4. If the Accept-Language header does not indicate a language preference, the default language for the PingOne environment is used.

    • Once the language preference has been determined, PingOne checks if there is a notification content that matches. If there is not an exact match, PingOne uses the best match (based on the language, ignoring the region) if available. For example, es-ES falls back to es.

    • For voice notifications, PingOne uses the best matching language based on the supported languages of the provider (Twilio, Syniverse, or a custom provider).

    • The locale property supports the syntax defined for the Accept-Language header in Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, including the use of quality values.

    Content language selection examples
    Content
    available
    languages    		 Voice
    provider
    support    		 User
    preferred
    language    		 Locale
    in the
    request    		 Resulting
    notification
    language    		 Description
    fr-CA
    it(default)    		 fr-CA
    it
    en    		 fr-CA fr-CA fr-CA User's preference and locale in the request match an available language in the content templates
    fr-CA
    it(default)    		 fr-CA
    it
    en    		 es es it Default content language used: neither user's preference nor locale in the request match an available content language
    fr-CA
    it(default)    		 fr-CA
    it
    en    		 es it Default content language used: no locale in the request, and no match of user's preference with available content languages
    fr-CA
    it(default)    		 fr-CA
    it
    en    		 es it Default content language used: no definition for user's preference, and no match of locale in the request with available content languages
    fr-CA
    it(default)    		 fr-CA
    it
    en    		 it Default content language used: no definition for both user's preference locale in the request
    fr-CA
    it(default)    		 fr-CA
    it
    en    		 es fr-CA fr-CA Locale in the request used: user's preference does not match an available language in the content templates, but the locale in the request does
    fr
    it(default)    		 fr
    it
    en    		 es fr-CA fr User preferred language doesn't match any of the available contents' locales, but locale in the request has a close match to an available content's locale (fr ~= fr-CA).
    fr-CA
    it    		 fr-CA
    it
    en    		 es es en Both user preferred language and locale in the request don't match an available content's locale and there's no available content for the environment's default language. Falling back to English.
    fr
    it(default)
    es    		 fr
    it
    en    		 fr es SMS,email,push:es
    Voice:fr    		 User preferred language matches an available content's locale (es). For notifications of type SMS, Email and Push, es will be used.
    Since es is not a supported voice language, for Voice notifications, fr will be used, since it matches the locale in the request and is also supported for text-to-speech.

    Creating custom contents

    Add and update custom contents with POST {{apiPath}}/environments/{{envID}}/templates/{{templateName}}/contents and PUT {{apiPath}}/environments/{{envID}}/templates/{{templateName}}/contents/{{contentID}}. Each content is associated with one template and has one deliveryMethod and one ISO language code (locale). You can define multiple custom contents for each template + deliveryMethod + locale combination with the variant property.

    Variants

    If you have more than one custom content that uses the same template, deliveryMethod, and locale, these contents must have different values for the variant property. The variant property holds the unique user-defined name for each content variant that uses the same template + deliveryMethod + locale combination.

    variant values can be reused by contents across different template + deliveryMethod + locale combinations. They need to be unique within the same template + deliveryMethod + locale combination only. As a best practice, use the same variant value for contents with the same message text. For example, the variant value variant_A can be used by a content with the strong_authentication + email + en combination and also by a content with the strong_authentication + push + en combination. For two contents that both use the strong_authentication + email + en combination though, if one content uses the variant value of variant_A, the other content must use a variant value such as variant_B.

    Use PATCH environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}} to bulk update the variant value in contents with the same variant value. Use DELETE environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}} to bulk delete contents with the same variant value.

    Variables

    Variables are placeholders for values that change depending on the context. For example:

    • The SMS content is Hi ${user.username}! Your one time passcode is ${otp}.
    • The ${user.username} variable has a value of John.
    • The ${otp} variable has a value of 548263.

    The resulting message is:
    Hi John! Your one time passcode is 548263, which includes the variable values John and 548263.

    Predefined variables

    If a template includes predefined variables, the template lists which variables can be optionally used in its contents and which variables are required in its contents. For example, user.username can be optionally used by strong_authentication contents, while otp is required for all SMS, Voice and Email contents.

    "variables": {
    "user.username": {
        "required": false
    },
    "otp": {
        "required": true,
        "requiredForDeliveryMethods": [
            "SMS",
            "Voice",
            "Email"
        ]
    }
}

    Dynamic variables

    In addition to predefined variables, most templates also allow dynamic variables. If a template has the property allowDynamicVariables set to true, its contents can contain any user-defined variable in the format ${variable_name}.

    Filtering result data

    You can filter GET {{apiPath}}/environments/{{envID}}/templates and GET {{apiPath}}/environments/{{envID}}/templates/{{templateName}}/contents results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, the following URL-encoded SCIM filter returns templates created before 2018-07-30 and updated after 2018-08-30:

    https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates?filter=(createdAt%20lt%20%222018-08-30%22)%20and%20(updatedAt%20gt%20%222018-07-30%22)%20

    SCIM operators can be applied to the following attributes:

    Collection Attribute Supported
    Templates and contents collections createdAt
    • eq (equals)
    • ne (not equals)
    • gt (greater than)
    • ge (greater than or equals)
    • lt (less than)
    • le (less than or equals)
    Templates and contents collections updatedAt
    • eq (equals)
    • ne (not equals)
    • gt (greater than)
    • ge (greater than or equals)
    • lt (less than)
    • le (less than or equals)
    Contents collections default
    • eq (equals)
    Contents collections locale
    • eq (equals)
    • sw (starts with)
    Contents collections deliveryMethod
    • eq (equals)
    Contents collections variant
    • eq (equals)
    • sw (starts with)

    Additionally, the logical and and or operators may be used for building compound expressions.

    Ordering result data

    You can order the collections returned by the GET collection endpoints according to the createdAt and updatedAt attribute. Ordering by any attribute returns the collection in a descending order. Using the attribute with the "-" prefix returns the collection ordered in descending order. For example, the following URL returns all the templates ordered by ascending creation date:

    https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates?order=-createdAt

    For more information about SCIM syntax and operators, see Conventions.

    Properties

    Template Properties
    Property Type Required? Mutable? Description
    id String Required Immutable The template id.
    displayName String Required Mutable The template’s display name.
    deliveryMethods Array Required Mutable The delivery methods supported for this template. Valid values are SMS, Voice, Email, and Push.
    createdAt Date N/A Read only The time the resource was created.
    updatedAt Date N/A Read only The time the resource was last updated.
    description String Optional Mutable The description of the template.
    variables Object Required Mutable Lists the variables you can use in each template content. The required property indicates whether the variable is required in template content. If required is true, the requiredForDeliveryMethods property lists the deliveryMethods types that require the variable. Note that if required is true, but requiredForDeliveryMethods is not returned, all deliveryMethods types are required. For more information, see Variables.
    allowDynamicVariables Boolean Required Mutable Specifies whether dynamic variables can be used in the template's contents. For more information, see Dynamic variables.
    Content Properties
    Property Type Required? Mutable? Description
    body String Required/Optional Mutable Only required when deliveryMethod is Email or Push. The email or push text (maximum 400 characters for push text). Email text cannot be larger than 100 kB. Email text can contain HTML. If supported, this can include variables.
    charset String Optional Mutable Relevant when deliveryMethod is Email. If not specified, UTF-8 is the default value.
    content String Required/Optional Mutable Only required when deliveryMethod is SMS or Voice. The SMS or voice text.
    • SMS: UC-2 encoding is used for text that contains non GSM-7 characters. UC-2 encoded text cannot exceed 67 characters. GSM-7 encoded text cannot exceed 153 characters. If supported, it can include variables.
    • Voice: Limited to 1Kb characters.
      The following substitution place holders can be embedded in the message:
      • <pause1sec>: Pauses the message narration for 1 second.
        The pause interval <pause1sec> cannot be modified. To pause the message narration for more than one second, repeat multiple <pause1sec> occurrences in succession, according to the desired pause interval duration. For example, <pause1sec><pause1sec><pause1sec> pauses the message narration for three seconds.
      • <sayCharValue> .. </sayCharValue>: Reads the character name of each character of the enclosed string separately.
      • <repeatMessage val=x> .. </repeatMessage>: Narrates the enclosed text <val> number of times.
      In the following message example, ${otp} is assigned the value "123456", and ${email} is assigned the value "joe@bxz.com":
      Hello <pause1sec> your authentication code is 
      <sayCharValue>${otp}</sayCharValue> 
      <repeatMessage val=2> I repeat your code is 
      <sayCharValue>${otp}</sayCharValue>
      </repeatMessage> <pause1sec> 
      Mail <sayCharValue>${email}</sayCharValue> for help
      The narrated message on the voice call sounds like:
      HELLO <1 second silence> YOUR AUTHENTICATION CODE IS 
      ONE TWO THREE FOUR FIVE SIX 
      I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX 
      I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX <1 second silence> 
      MAIL JAY OH EE AT BEE EX ZEE DOT SEE OH EM FOR HELP
    createdAt Date N/A Read only The time the resource was created.
    default Boolean Optional Mutable Specifies whether the template is a predefined default template.
    deliveryMethod String Required Immutable The content's delivery method. Possible values are Email, SMS, Voice, Push, and WhatsApp. Cannot be changed after it is initially set in POST {{apiPath}}/environments/{{envID}}/templates/{{templateName}}/contents.
    emailContentType String Optional Mutable Relevant when deliveryMethod is Email. If not specified, text/html is the default value.
    from.address String Optional Mutable Relevant when deliveryMethod is Email.
    The sender email address.
    If the environment uses the Ping Identity email sender, or if the address field is empty, the address "noreply@pingidentity.com" is used.
    You can configure other email sender addresses per environment.
    See Note for details.
    from.name String Optional Mutable Relevant when deliveryMethod is Email.
    The email's sender name.
    If the environment uses the Ping Identity email sender, the name "PingOne" is used.
    You can configure other email sender names per environment.
    See Note for details.
    id String N/A Read only The template id.
    locale String Required Immutable A valid case-insensitive locale, complying with the ISO-639 language code and ISO-3166 country code standards:
    • Two-character language code, for example, "en".
    • Two-character language code followed by a two-character country code, separated by an underscore or dash, for example: "en_GB", "en-GB".
    Cannot be changed after it is initially set in POST {{apiPath}}/environments/{{envID}}/templates/{{templateName}}/contents.
    pushCategory String Optional Mutable For Push content, you can specify what type of banner should be displayed to the user. The available options are:
    • BANNER_BUTTONS - the banner contains both Approve and Deny buttons
    • WITHOUT_BANNER_BUTTONS - when the user clicks the banner, they are taken to an application that contains the necessary approval controls.
    • APPROVE_AND_OPEN_APP - when the Approve button is clicked, authentication is completed and the user is taken to the relevant application.
    If this parameter is not provided, the default is BANNER_BUTTONS. Note that to use the non-default push banners, you must implement them in your application code, using the PingOne SDK. For details, see the README for iOS and the README for Android.
    replyTo.address String Optional Mutable Relevant when deliveryMethod is Email.
    The "reply to" email address.
    If the environment uses the Ping Identity email sender, or if the address field is empty, the address "noreply@pingidentity.com" is used.
    You can configure other email "reply to" addresses per environment.
    See Note for details.
    replyTo.name String Optional Mutable Relevant when deliveryMethod is Email.
    The email's "reply to" name.
    If the environment uses the Ping Identity email sender, the name "PingOne" is used.
    You can configure other email "reply to" names per environment.
    See Note for details.
    sender String Optional Mutable Relevant when deliveryMethod is SMS. The SMS sender ID. This property can contain only alphanumeric characters and spaces, and its length cannot exceed 11 characters. In some countries, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For SMS recipients in specific countries, refer to Twilio's documentation on International support for Alphanumeric Sender ID.
    subject String Optional Mutable Relevant when deliveryMethod is Email. The email's subject line. Cannot exceed 256 characters. If supported, can include variables.
    title String Optional Mutable Relevant when deliveryMethod is Push. The push title (maximum 200 characters). If supported, this can include variables.
    updatedAt Date N/A Read only The time the resource was last updated.
    variant String Optional Mutable Holds the unique user-defined name for each content variant that uses the same template + deliveryMethod + locale combination. This property is case insensitive and has a limit of 100 characters. For more information, see Creating custom contents.
    voice String Optional Mutable Relevant only if deliveryMethod is Voice. Options are Alice, Man, or Woman.
    Voice OTP supports vendor-specific voices.
    • Supported Twilio voices:
      • Man, Woman
        Supported locales (default: en):
        en, en_GB, es, fr, de
      • Alice (Twilio only)
        Supported locales (default: en US):
        da_DK, de_DE, en_AU, en_CA, en_GB, en_US, ca_ES, es_ES, es_MX, fi_FI, fr_CA, fr_FR, it_IT, ja_JP, ko_KR, nb_NO, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, zh_CN, zh_HK, zh_TW
      • Amazon Polly
        cy_GB, ro_RO, is_IS, hi_IN tr_TR
    • Supported Syniverse voices:
      • Man, Woman
        Supported locales:
        en_US, en_GB, es_ES, es_US, fr_FR, de_DE, it_IT, en_AU, da_DK, is_IS, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, ja_JP
      • Woman only
        Supported locales:
        cmn_CN, cy_GB, en_IN, fr_CA, hi_IN, nb_NO, ro_RO, sv_SE, tr_TR, ko_KR, ar
    whatsAppTemplate Object Required Mutable Required when creating content for WhatsApp delivery. Contains the necessary information for identifying the WhatsApp template that should be used for the content. Use {{apiPath}}/environments/{{envID}}/notificationsSettings/instantMessagingDeliverySettings/whatsApp?expand=whatsAppTemplates to get the details of all the available WhatsApp templates, as shown in the Read WhatsApp Delivery Settings (including templates) example. Note that the object returned for each template is identical in structure to the structure of the whatsAppTemplate object, so template details can be copied directly from that response.
    whatsAppTemplate.category String Optional Mutable If included, should be set to AUTHENTICATION.
    whatsAppTemplate.id String Required Mutable The WhatsApp-provided ID of the template.
    whatsAppTemplate.language String Required Mutable The language of the template.
    whatsAppTemplate.name String Required Mutable The name of the template.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notifications NOTIFICATION.CREATED
    notifications NOTIFICATION.UPDATED
    notifications NOTIFICATION.REJECTED
    templates CONTENT.CREATED
    templates CONTENT.UPDATED
    templates CONTENT.DELETED

    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.
    404 The requested resource was not found.

    Create Email Content

    Create WhatsApp Content

    Create SMS Content

    Create Voice Content

    Create Push Content

    Read All Templates

    Read All Contents

    Read One Template

    Read One Content

    Update Email Content

    Update WhatsApp Content

    Update SMS Content

    Update Voice Content

    Update Push Content

    Delete Content

    Patch Bulk Variant Contents

    Delete Bulk Variant Contents

    Notifications Settings

    The notifications settings endpoints provide the ability to configure specific notifications settings for each environment. They implement operations to read, update and reset the settings for the environment.

    Configure an SMS/Voice provider fallback chain

    The sequence of SMS/Voice providers in smsProvidersFallbackChain comprises the notification fallback sequence, in the event of a primary or subsequent provider failing to send the notification.

    1. The providers must be configured in the Phone Delivery Settings resource.
    2. Update the notifications setting resource by using the PUT {{apiPath}}/environments/{{envID}}/notificationsSettings/ operation. For example, to define your own provider (represented here as TwilioPhoneDeliverySettingsId) as the primary provider, and Ping's Twilio account as the fallback:
    {
    "smsProvidersFallbackChain": [ "TwilioPhoneDeliverySettingsId", "PINGONE_TWILIO" ]
}

    Notifications settings properties

    Property Type Required? Mutable? Description
    environment.id String Required Immutable The environment resource’s unique identifier.
    from.name String Optional Mutable The email's "from" name.
    See Note for details.
    from.address String Optional Mutable The email's "from" address. This value must be a trusted email address.
    See Note for details.
    replyTo.name String Optional Mutable The email's "reply to" name.
    See Note for details.
    replyTo.address String Optional Mutable The email's "reply to" address. This value must be a trusted email address.
    See Note for details.
    smsProvidersFallbackChain String[] Optional Mutable A comma-separated list that represents the execution order of different SMS/Voice providers configured for the environment. The providers and their accounts’ configurations are represented in the list by the ID of the corresponding PhoneDeliverySettings resource. The only provider which is not represented by a PhoneDeliverySettingsId is the PingOne Twilio provider. The PingOne Twilio provider is represented by the "PINGONE_TWILIO" string. If the smsProvidersFallbackChain list is empty, an SMS or voice message will be sent using the default Ping Twilio account. Otherwise, an SMS or voice message will be sent using the first provider in the list. If the server fails to queue the message using that provider, it will use the next provider in the list to try to send the message. This process will go on until there are no more providers in the list. If the server failed to send the message using all providers, the notification status is set to FAILED.
    updatedAt Date N/A Read-Only The time the resource was last updated.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notifications NOTIFICATIONS_SETTINGS.UPDATED

    Notifications settings response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    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.

    Read Notifications Settings

    Update Notifications Settings

    Delete Notifications Settings

    Notification Policies

    You can define notification policies to limit the use of SMS/voice and email notifications for pairing and authentication.

    Parameters for creating/updating notification policies
    Property Type Required? Mutable? Description
    cooldownConfiguration Object Optional Mutable Include the cooldownConfiguration object in the request if you want to specify a period of time that users must wait before requesting an additional notification such as an additional OTP.
    cooldownConfiguration.email Object Required Mutable Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for email notifications.
    cooldownConfiguration.sms Object Required Mutable Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for sms notifications.
    cooldownConfiguration.voice Object Required Mutable Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for voice notifications.
    cooldownConfiguration.whatsApp Object Required Mutable Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for whatsApp notifications.
    cooldownConfiguration.(authentication method).enabled Boolean Required Mutable Set to true if you want to specify notification cooldown periods for the authentication method. Set to false if you don't want notification cooldown periods for this authentication method.
    cooldownConfiguration.(authentication method).periods Array Required Mutable Use the periods array to specify the amount of time the user has to wait before requesting another notification such as another OTP. The array should contain three objects: the time to wait before the first retry, the time to wait before the second retry, and the time to wait before any subsequent retries.
    cooldownConfiguration.(authentication method).periods[].duration Integer Required Mutable Used in conjunction with timeUnit to specify the waiting period. Minimum is ten seconds, maximum is ten minutes.
    cooldownConfiguration.(authentication method).periods[].timeUnit String Required Mutable Used in conjunction with duration to specify the waiting period. Can be set to SECONDS or MINUTES.
    cooldownConfiguration.(authentication method).groupBy String Optional Mutable Since bad actors may try to target multiple users at a single email address or phone number, by default the cooldown settings (both waiting period and maximum retries) are applied to the email address or phone number. If you want the settings to be applied at the single-user level for the address/number, include the groupBy parameter in the request and set it to USER_ID.
    cooldownConfiguration.(authentication method).resendLimit Integer Required Mutable The maximum number of requests that a user can send to receive another notification, such as another OTP, before they are blocked for 30 minutes.
    countryLimit Object Optional Mutable You can use the countryLimit object to limit the countries where you can send SMS and voice notifications.
    countryLimit.type String Required/Optional Mutable Determines the kind of limitation being defined. The possible values are
    • NONE
    • ALLOWED - allows SMS/Voice notifications only for the countries specified with countryLimit.countries
    • DENIED - denies SMS/Voice notifications for the countries specified with countryLimit.countries
    countryLimit.deliveryMethods Array Optional Mutable The delivery methods that the defined limitation should be applied to. Content of the array can be SMS, Voice, or both. If the parameter is not provided, the default is SMS and Voice.
    countryLimit.countries Array Required/Optional Mutable The countries where the specified methods should be allowed or denied. Use the two-letter country codes from ISO 3166-1.
    createdAt Date N/A Read-only The date and time the notification policy was created.
    default Boolean Optional Mutable Indication of whether this policy is the default notification policy for the environment. If the parameter is not provided, the value used is false
    environment.id String N/A Read-only The ID of the PingOne environment that contains the notification policy.
    id String N/A Read-only The ID generated for the notification policy when it was created.
    name String Required Mutable The name to use for the notification policy. Must be unique among the notification policies in the environment.
    providerConfiguration Object Optional Mutable If you have defined more than one custom provider, you can use the providerConfiguration object to specify the provider preference to use for different countries and for the different methods (SMS and Voice).
    providerConfiguration.conditions Array Optional Mutable Each element in the conditions array represents the provider fallback order to use for a specific group of countries for the specified methods (SMS and/or Voice). Note that in addition to any country-specific orders specified, the array must contain a fallback order without the countries array in the object. This order is used for all countries that were not specified in one of the other fallback orders defined.
    providerConfiguration.conditions[].deliveryMethods Array Optional Mutable The authentication methods that the fallback order should be used for. The array can contain VOICE, SMS, or both.
    providerConfiguration.conditions[].countries Array Optional Mutable The countries for which the fallback order should be used. Use the two-letter country codes from ISO 3166-1.
    providerConfiguration.conditions[].fallbackChain Array Optional Mutable An array containing the IDs of the defined custom providers, in the order that they should be used if available.
    providerConfiguration.conditions[].fallbackChain.id String Optional Mutable The ID of one of the defined custom providers. This is the ID that is returned when you create the provider using the phoneDeliverySettings endpoint or when you run the GET request with that endpoint to retrieve the details of all the providers.
    quotas Array Required Mutable Collection of objects that define the SMS/voice and email limits. Each object contain the following elements: type, deliveryMethods, total. Note that instead of total, you can use the pair of fields: claimed and unclaimed.
    quotas[].type String Required Mutable Specifies whether the limit defined is per-user or per environment. Value must be either USER or ENVIRONMENT.
    quotas[].deliveryMethods Array Required Mutable The delivery methods for which the limit is being defined. The value can be Email or SMS,Voice. When you use the SMS, Voice option, it means that the combined total of SMS and voice notifications must be below the limit defined. If you are limiting both email and SMS/voice, each limit should be represented by a different object in the quotas array, for example:
    "quotas": [{"type": "USER","deliveryMethods": ["SMS","Voice"],"total": 30},{"type": "USER","deliveryMethods": ["Email"],"total": 30}]
    quotas[].total Integer Required/Optional Mutable The maximum number of notifications allowed per day.
    quotas[].claimed Integer Required/Optional Mutable The maximum number of notifications that can be received and responded to each day. Used in conjunction with unclaimed in place of the single field total.
    quotas[].unclaimed Integer Required/Optional Mutable The maximum number of notifications that can be received and not responded to each day. Used in conjunction with claimed in place of the single field total.
    updatedAt Date N/A Read-only The date and time the notification policy was last updated.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notification_policy NOTIFICATION_POLICY.CREATED
    notification_policy NOTIFICATION_POLICY.UPDATED
    notification_policy NOTIFICATION_POLICY.DELETED

    When you create/update a notification policy, the response also includes the following information:

    • id - the ID assigned to the notification policy
    • createdAt - date and time when the policy was created
    • updatedAt - date and time when the policy was updated

    Create Notification Policy / Environment

    Create Notification Policy / Environment (using custom providers)

    Create Notification Policy / User

    Create Notification Policy / user - claimed, unclaimed (instead of total)

    Update Notification Policy (with custom provider preference)

    Read All Notification Policies

    Read One Notification Policy

    Update Notification Policy

    Delete Notification Policy

    Reset Notification Quotas

    Notifications Settings (SMTP)

    The SMTP notifications settings endpoints provide the ability to configure the organization's own SMTP service to send email notifications for each environment, instead of the built-in email service of PingOne. These endpoints implement operations to read, update and reset the SMTP notification settings for the environment.

    Notifications settings (SMTP) properties
    Property Type Mutability Description
    host String Mutable The organization's SMTP server.
    port String Mutable The port used by the organization's SMTP server to send emails. The default port is 465.
    protocol String Read-only The SMTP protocol used by the organization. Ports 25, 2525, and 587 use SMTP. All other ports use SMTPS.
    username String Mutable The organization's SMTP server username.
    password String Write-only The organization's SMTP server password. Encrypted.
    environment.id String Read-only The environment resource’s unique identifier.
    from.name String Mutable The email's "from" name .
    from.address String Mutable The email's "from" address.
    replyTo.name String Mutable The email's "reply to" name.
    replyTo.address String Mutable The email's "reply to" address.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notifications NOTIFICATIONS_SETTINGS.UPDATED

    Read Notifications Settings (SMTP)

    Update Notifications Settings (SMTP)

    Delete Notifications Settings (SMTP)

    Email Delivery Settings

    Use the emailDeliverySettings endpoint to configure the sending of notifications via an external email service.

    Note that you can only have a single set of email delivery settings for an environment, whether it be a custom SMTP mail server or an external email service.

    Email delivery settings data model
    Property Type Required? Mutable? Description
    authentication Object Required Mutable Contains the information for authenticating with the email provider.
    authentication.method String Required Mutable Use the value BASIC if your authentication with the email provider uses a username and password. Use BEARER if your authentication is based on the use of a bearer token.
    authentication.authToken String Optional Mutable If you specified BEARER as the authentication method, use authToken to provide the bearer token to use.
    authentication.username String Optional Mutable If you specified BASIC as the authentication method, use username to provide the username for authenticating with the email provider.
    authentication.password String Optional Mutable If you specified BASIC as the authentication method, use password to provide the password for authenticating with the email provider.
    environment.id String N/A Read-only The environment's unique identifier.
    from Object Optional Mutable Contains the "from" information to use for the notifications.
    from.name String Optional Mutable The "from" name to use in the notifications that are sent.
    from.address String Optional Mutable The "from" address to use in the notifications that are sent.
    name String Required Mutable Name to use to identify the provider.
    protocol String Required Immutable Set to HTTP when configuring an external email provider.
    provider String Required Immutable Must be set to CUSTOM_PROVIDER.
    replyTo Object Optional Mutable Contains the "reply-to" information to use for the notifications.
    replyTo.name String Optional Mutable The "reply-to" name to use in the notifications that are sent.
    replyTo.address String Optional Mutable The "reply-to" address to use in the notifications that are sent.
    requests Array Required Mutable Contains the object that is used to configure the API requests sent to the email provider.
    requests[].body String Required Mutable Required if method is set to POST. Use body to provide the content of the body for the request sent to the email provider. The body that you define must include the mandatory PingOne variables for notifications: ${from}, ${to}, and ${message}. You can also include any optional notification variables.
    If you are including the header content-type: application/json in requests[].headers:
    • The content of requests[].body must be valid JSON
    • You must enclose the JSON object in quotation marks and escape all quotation marks within the string, for example, "{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}".
    requests[].deliveryMethod String Required Immutable Should be set to EMAIL.
    requests[].headers Object Required Mutable Use this object to specify the headers that your email provider's API expects.
    requests[].method String Required Mutable Use method to specify the type of API request the email provider requires. Valid values are GET and POST.
    requests[].url String Required Mutable Use url to specify the endpoint for your email provider, for example, https://api.example.com/email. If method is set to GET, append to the URL the various query parameters that the email provider's API requires. The URL must also include the required PingOne variables, as described for the body parameter.
    updatedAt Date N/A Read-only The date and time the email delivery settings were last updated.

    Create Custom Email Provider

    Read Custom Email Provider

    Phone Delivery Settings

    The phone delivery settings endpoints provide the ability to configure different accounts which could be used for sending an SMS or voice message. They implement operations to create, update, read and delete phone delivery settings resources for an environment.

    Phone delivery settings properties
    Property Type Required? Mutable? Description
    id String Required Immutable The auto-generated ID of the phone delivery settings.
    environment.id String Required Immutable The relationship of the phone delivery settings to the environment.
    provider String Required Immutable The provider to use for phone delivery service. Possible values:
    • CUSTOM_TWILIO: Uses the default PingOne provider (Twilio / Vonage) as the SMS/voice provider.
    • CUSTOM_SYNIVERSE: Specifies that your Syniverse account is the SMS/voice provider.
    • CUSTOM_PROVIDER: Uses the custom SMS provider that you defined (if you want to use a provider other than the default PingOne provider or Syniverse).
    createdAt Date N/A Read-only The time the resource was created.
    updatedAt Date N/A Read-only The time the resource was last updated.

    Custom provider phone delivery settings properties (Twilio or Syniverse)

    The phoneDeliverySettings instance that supports your Twilio or Syniverse custom provider phone delivery accounts.

    Property Type Required? Mutable? Description
    id String Required Immutable The auto-generated ID of the phone delivery settings.
    environment.id String Required Immutable The relationship of the phone delivery settings to the environment.
    sid String Required Immutable The public ID of the Twilio account.
    Relevant to Twilio only.
    authToken String Required Immutable The secret key of the Twilio or Syniverse account.
    provider String Required Immutable The ID of the provider of phone delivery service. In this case it has the value CUSTOM_TWILIO or CUSTOM_SYNIVERSE, depending on your vendor.
    createdAt Date N/A Read-only The time the resource was created.
    updatedAt Date N/A Read-only The time the resource was last updated.
    numbers Array Required Mutable A collection of Twilio or Syniverse numbers to use when sending a notification. The array uses the properties in the Custom provider phone number properties data model. If left blank, returns the numbers from the Twilio or Syniverse service.
    Custom provider phone delivery settings properties (excluding Twilio and Syniverse)

    The phoneDeliverySettings instance that supports your custom provider phone delivery accounts (excluding Twilio and Syniverse).

    Property Type Required? Mutable? Description
    name String Required Mutable The customer provider's name.
    requests.deliveryMethod String Required Mutable The notification's delivery method. Possible value:
    • SMS
    • VOICE
    requests.url String Required Mutable The provider's remote gateway or customer gateway URL.
    • For requests using the POST method, use the provider's remote gateway URL.
    • For requests using the GET method, use the provider's remote gateway URL, including the ${to} and ${message} mandatory variables. The ${from} variable is required if the numbers attribute is set, and any object in the number array is selected. For example:
      https://api.transmitsms.com/send-sms.json?to=${to}&from=${from}&message=${message}"
    requests.body String Optional Mutable The notification's request body. This property is required when requests.method is set to POST. The body should include the ${to} and ${message} mandatory variables. The ${from} variable is required if the numbers attribute is set, and any object in the number array is selected. For example:
    messageType=ARN&message=${message}&phoneNumber=${to}&sender=${from}
    In addition, you can use the following optional variables:
    • ${voice} - the type of voice configured for notifications
    • ${locale} - locale
    • ${otp} - OTP
    • ${user.user.name} - user's username
    • ${user.name.given} - user's given name
    • ${user.name.family} - user's family name
    You can also use dynamic variables in the body. For more information, see Dynamic variables.
    requests.headers String[] Optional Mutable The notification's request header, matching the format of the request body. When the request.method value is POST, it can be one of:
    • Form
      (content-type=application/x-www-form-urlencoded)
    • JSON
      (content-type=application/json)
    Otherwise, custom header values are also allowed.
    requests.method String Required Mutable The type of HTTP request method. Possible values:
    • GET
    • POST
    requests.phoneNumberFormat String Required Mutable The phone number format. Possible values:
    • FULL (default)
      The phone number format with a leading + sign, in the E.164 standard format.
      For example: +14155552671
    • NUMBER_ONLY
      The phone number format without a leading + sign, in the E.164 standard format.
      For example: 14155552671
    requests.beforeTag String Optional Mutable For voice OTP notifications only.
    An opening tag which is commonly used by custom providers for defining a pause between each number in the OTP number string.
    Possible value: <Say>
    requests.afterTag String Optional Mutable For voice OTP notifications only.
    A closing tag which is commonly used by custom providers for defining a pause between each number in the OTP number string.
    Possible value: </Say> <Pause length="1"/>
    authentication.method String Required Mutable The custom provider account's authentication method. Possible values:
    • BASIC
    • BEARER
    authentication.username String Required/Optional Mutable The username for the custom provider account.
    Required when authentication.method=BASIC
    authentication.password String Required/Optional Mutable The password for the custom provider account.
    Required when authentication.method=BASIC
    authentication.authToken String Required/Optional Mutable The authentication token for the custom provider account.
    Required when authentication.method=BEARER
    numbers Array Required Mutable A collection of Twilio or Syniverse numbers to use when sending a notification. The array uses the properties in the Custom provider phone number properties data model.

    Custom provider phone number properties
    Property Type Required? Mutable? Description
    type String Required Mutable The type of phone number. Possible values: SHORT_CODE, TOLL_FREE, PHONE_NUMBER
    selected Boolean Required Mutable Specifies whether the number is selected by the admin for sending messages.
    createdAt Date N/A Read-only The time the resource was created.
    number String Required Mutable The phone number, toll-free number or short code.
    available Boolean Required Mutable Specifies whether the number is currently available in the provider account.
    capabilities String[] Required Mutable A collection of the phone delivery service capabilities. Possible values: VOICE, SMS. See the Phone delivery capabilities properties data model.
    supportedCountries String[] Required Mutable Specifies the number's supported countries for notification recipients, depending on the phone number type:
    • SHORT_CODE: A collection containing a single 2-character ISO country code, for example, US, GB, CA.
      If the custom provider is of type=CUSTOM_PROVIDER, supportedCountries must not be empty or null.
      For other custom provider types, if supportedCountries is null (empty is not supported), the specified short code number can only be used to dispatch notifications to United States recipient numbers.
    • TOLL_FREE: A collection of valid 2-character country ISO codes, for example, US, GB, CA.
      If the custom provider is of type=CUSTOM_PROVIDER, supportedCountries must not be empty or null.
      For other custom provider types, if supportedCountries is null (empty is not supported), the specified toll-free number can only be used to dispatch notifications to United States recipient numbers.
    • PHONE_NUMBER: supportedCountries can not be specified.
    If an SMS template has an alphanumeric sender ID and also has short code, the sender ID will be used for destination countries that support both alphanumeric senders and short codes. For Unites States and Canada that don't support alphanumeric sender IDs, a short code will be used if both an alphanumeric sender and a short code are specified.

    Phone delivery capabilities properties
    Property Type Required? Mutable? Description
    capability String Required Mutable The type of phone delivery service capability. Possible values: VOICE, SMS.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notifications PHONE_DELIVERY_SETTINGS.CREATED
    notifications PHONE_DELIVERY_SETTINGS.UPDATED
    notifications PHONE_DELIVERY_SETTINGS.DELETED

    Phone delivery settings response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    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.

    Configure your custom phone delivery vendor account (Twilio or Syniverse)

    1. Create a custom Twilio or Syniverse phone delivery settings resource using the POST {{apiPath}}/environments/{{envID}}/notificationsSettings/phoneDeliverySettings operation. Twilio:
    {
  "sid": "someSid",
  "authToken": "someAuthToken",
  "provider": "CUSTOM_TWILIO"
}

    For Syniverse, remove the sid property in the above example, and set "provider": "CUSTOM_SYNIVERSE".

    1. Use the PUT {{apiPath}}/environments/{{envID}}/notificationsSettings/phoneDeliverySettings/{{phoneDeliverySettingID}} to select the numbers you would like to use for sending messages, by marking them as selected. The Twilio example is as follows:
    {
  "id": "someTwilioPhoneDeliverySettingsId",
  "sid": "someSid",
  "provider": "CUSTOM_TWILIO",
  "numbers": [
    {
      "type": "SHORT_CODE",
      "capabilities": [
        "SMS"
      ],
      "selected": true,
      "available": true,
      "number": "894546"
    },
    {
      "type": "TOLL_FREE",
      "capabilities": [
        "SMS"
      ],
      "selected": false,
      "available": true,
      "number": "+18544440098"
    },
    {
      "type": "PHONE_NUMBER",
      "capabilities": [
        "SMS",
        "VOICE"
      ],
      "selected": true,
      "available": true,
      "number": "+172544440091"
    }
  ]
}

    For Syniverse, remove the sid property in the above example, and set "provider": "CUSTOM_SYNIVERSE".

    The sequence of SMS/Voice providers in the notification settings resource's smsProvidersFallbackChain comprises the notification fallback sequence, in the event of a primary or subsequent provider failing to send a notification. See Notifications Settings for details on configuring an SMS/Voice provider fallback chain.

    Configure your custom phone delivery vendor account (excluding Twilio and Syniverse)

    Create a custom phone delivery settings resource using the POST {{apiPath}}/environments/{{envID}}/notificationsSettings/phoneDeliverySettings operation. Create phone delivery settings:

    --header 'Content-Type: application/json' \
--header 'Authorization: Bearer <insert access token>' \
--data-raw '{
  "name": "Custom Provider Name",
  "provider":"CUSTOM_PROVIDER",
  "authentication":{
      "method":"BASIC",
      "username":"<username>",
      "password":"<password>"
    },
  "requests":[{
      "deliveryMethod":"SMS",
      "url":"<Custom provider API URL>",
      "method":"POST",
      "body":"messageType=ARN&message=${message}&phoneNumber=${to}&sender=${from}"
    }],
    "numbers":[{"type":"PHONE_NUMBER","number":"+1 222 333","capabilities":["SMS"]}]
}'

    After the admin has updated the provider configuration, PingOne will send the following POST request to your gateway every time a user signs up, logs in, adds a new device, or issues another SMS or voice notification:

    curl --request POST '<Custom provider API URL>' \
--header 'content-type: application/json' \
--header 'Authorization: Basic QUN...YQ==' \
--data-raw '{ 
   "message": "<notification message>",
   "to": "<user phone number>",
   "from": "<sender phone number>"
 }'

    Create Phone Delivery Settings

    Create Phone Delivery Settings (Twilio)

    Create Phone Delivery Settings (Syniverse)

    Read All Phone Delivery Settings

    Read One Phone Delivery Settings

    Update Phone Delivery Settings

    Update Phone Delivery Settings (Twilio)

    Delete Phone Delivery Settings

    Trusted Email Domains

    PingOne supports the ability to configure up to 50 trusted email domains for each environment. A trusted email domain with its associated email addresses enable PingOne to send emails on your organization’s behalf. To implement a trusted email domain, you’ll need to add DNS records and setup DKIM and SPF.

    To create and manage trusted email addresses associated with your trusted email domain, see Trusted email addresses.

    Trusted email domain properties

    Property Type Required? Mutable? Description
    id String Required Immutable The auto-generated ID of the email domain.
    domainName String Required Mutable A string that specifies the resource name, which must be provided and must be unique within an environment (for example, auth.shopco.com). Wildcards are NOT supported.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.

    Trusted email domain ownership properties

    Property Type Required? Mutable? Description
    environmentDnsRecord Object N/A Read-only environmentDnsRecord contains a key-value pair for a text record that reflects the association of the domain with the specific PingOne environment. If you add this record to your DNS, any sender email address belonging to the domain is set to active status as soon as you create it, with no need for a verification email. In addition to key and value, the object contains a status field. In the initial call to check ownership status, status is returned with the value VERIFICATION_REQUIRED. If you add the record to your DNS, the next time you use the ownership endpoint to check ownership status, the value returned for status will be ACTIVE.
    regions Object[] Required Immutable The regions collection specifies the properties for the 4 AWS SES regions that are used for sending email for the environment. The regions are determined by the geography where this environment was provisioned (North America, Canada, Europe & Asia-Pacific). Each item in the regions collection is an object with these properties:
    • name: The name of the region.
    • status: The status of the email domain ownership. Possible values:
      • ACTIVE
      • VERIFICATION_REQUIRED
    • key: Record name.
    • value: Record value.
    type String Required Mutable The type of DNS record, with the value "TXT".

    Trusted email domain DKIM properties

    Property Type Required? Mutable? Description
    type String Required Mutable The type of DNS record, with the value "CNAME".
    regions Object[] Required Immutable The regions collection specifies the properties for the 4 AWS SES regions that are used for sending email for the environment. The regions are determined by the geography where this environment was provisioned (North America, Canada, Europe & Asia-Pacific). Each item in the regions collection is an object with these properties:
    • name: The name of the region.
    • status: The status of the email domain ownership. Possible values:
      • ACTIVE
      • VERIFICATION_REQUIRED
    • tokens: A collection of key and value pairs. Each item in the tokens collection is an object with these properties:
      • key: Record name.
      • value: Record value.

    Trusted email domain SPF properties

    Property Type Required? Mutable? Description
    type String Required Mutable The type of DNS record, with the value "TXT".
    status String Required Mutable The status of the email domain ownership. Possible values:
    • ACTIVE
    • VERIFICATION_REQUIRED
    key String Required Mutable Record name.
    value String Required Mutable Record value.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notifications EMAIL_DOMAIN.CREATED
    notifications EMAIL_DOMAIN.DELETED

    Trusted email domains 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.

    Create Trusted Email Domain

    Read All Trusted Email Domains

    Read One Trusted Email Domain

    Read Trusted Email Domain Ownership Status

    Read Trusted Email Domain DKIM Status

    Read Trusted Email Domain SPF Status

    Delete Trusted Email Domain

    Trusted Email Addresses

    PingOne supports the ability to configure up to 10 trusted email address for an existing trusted email domain. See Trusted email domains.

    Trusted email addresses properties

    Property Type Required? Mutable? Description
    id String Required Immutable The auto generated ID of the trusted email address.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.
    emailDomain.id String Required Immutable The trusted email domain resource’s unique identifier associated with the resource.
    emailAddress String Required Mutable The trusted email address, for example john.smith@shopco.com.
    status String Required Mutable The status of the trusted email address. Possible values:
    • ACTIVE
    • VERIFICATION_REQUIRED

    Trusted email address activation request properties

    Property Type Required? Mutable? Description
    verificationCode String Required Immutable A string that specifies a one-time passcode sent to the trusted email address.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    notifications TRUSTED_EMAIL_CREATED
    notifications TRUSTED_EMAIL_DELETED
    notifications TRUSTED_EMAIL_SEND_CODE
    notifications TRUSTED_EMAIL_ACTIVE

    Trusted email addresses 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.

    Create Trusted Email Address

    Read All Trusted Email Addresses

    Read One Trusted Email Address

    Activate Trusted Email Address

    Resend Verification Code To Email

    Delete Trusted Email Address

    Send Notification

    You can use the notifications endpoint to send a test notification to a mobile application by including the query parameter sync=true.

    {{apiPath}}/environments/{{envID}}/notifications?sync=true

    Send Notifications data model

    Property Type? Required? Mutable? Description
    application.id Sting Required Immutable The ID of the mobile application associated with the push message.
    body String Required Immutable The text for the body of the push message.
    createdAt Date N/A Read-only The time the resource was created.
    data.type String Required Immutable Must be set to DRY for the test to work correctly.
    deliveryMethod String Required Immutable The messaging service to be used. Should be one of the following values: GOOGLE, HUAWEI, IOS.
    environment.id String N/A Read-only The ID of the relevant PingOne environment.
    id String N/A Read-only The ID of the resource created.
    policy.id String N/A Read-only The ID of the notification policy.
    pushToken String Required Immutable The push token for the relevant application on the device.
    status String N/A Read-only The result of the test push. If the push succeeded, value will be SENT. If there was a problem, a standard error response will be returned, containing details of the cause.
    title String Required Immutable The title for the push message.
    updatedAt Date N/A Read-only The time the resource was last updated.
    vendor String N/A Read-only The type of push credential used. Will be APNS (for Apple), FCM_HTTP_V1 (for Google), HMS (for Huawei), or FCM (used previously for Google, now deprecated).

    Test Push Notifications

    Instant Messaging Delivery Settings

    Use the /instantMessagingDeliverySettings/whatsApp endpoint to configure the sending of PingOne notifications via WhatsApp.

    WhatsApp delivery settings data model
    Property Type Required? Mutable? Description
    appId String Required Mutable The ID of the WhatsApp app you are using for sending the notifications.
    appSecret String Required Mutable The secret for the WhatsApp app you are using for sending the notifications.
    createdAt Date N/A Read-only Date and time that the delivery settings were created.
    environment.id String N/A Read-only The ID of the PingOne environment.
    id String N/A Read-only The ID assigned to the delivery settings.
    numbers[] Array Optional Mutable The numbers array is included in the response when creating WhatsApp settings. It contains information about the various phone numbers available for use with the app ID that was specified in the creation request. If there is more than one number available for the app, a second PUT request can be run to specify the number to use for sending notifications. To specify the number to use, include the numbers array in your request, set numbers[].selected to true, and specify the number ID with numbers[].numberId or the number itself with numbers[].number.
    numbers[].available Boolean N/A Read-only Specifies whether the number is currently available in the account.
    numbers[].capabilities Array N/A Read-only For WhatsApmp settings, will always consist of a single element, WHATSAPP.
    numbers[].createdAt Date N/A Read-only The time the resource was created.
    numbers[].number String Required Mutable The number for sending notifications.
    numbers[].numberId String Required Mutable The ID of the number for sending notifications.
    numbers[].qualityRating String N/A Read-only The current WhatsApp quality rating for the number.
    numbers[].selected Boolean Required Mutable Set to true when specifying a specific number to use for sending notifications.
    numbers[].type String N/A Read-only For WhatsApp settings, the value returned is WHATSAPP.
    numbers[].verifiedName String N/A Read-only The verified name for the number.
    provider String Required Mutable For configuring WhatsApp settings, set the value to CUSTOM_WHATSAPP.
    userAccessToken String Required Mutable The access token for the WhatsApp business account.
    whatsAppAccountBusinessId String Required Mutable The ID of the WhatsApp business account.
    status String N/A Read-only The status of the creation of the delivery settings. In the response to the create request, the value is Pending. Status changes to Created after the configuration has been completed.
    type String N/A Read-only For WhatsApp settings, the value returned is WHATSAPP.
    updatedAt Date N/A Read-only Date and time that the delivery settings were last updated.
    whatsAppTemplate Object N/A Read-only Included in the response if you included expand=whatsAppTemplates as a query parameter when getting the WhatsApp delivery settings. See the Read WhatsApp Delivery Settings (including templates) example.
    whatsAppTemplate.category String N/A Read-only The category of the template. Currently will always be AUTHENTICATION.
    whatsAppTemplate.id String N/A Read-only The WhatsApp-provided ID of the template.
    whatsAppTemplate.language String N/A Read-only The language of the template.
    whatsAppTemplate.name String N/A Read-only The name of the template.

    Create WhatsApp Delivery Settings

    Create WhatsApp Delivery Settings (specify number)

    Read WhatsApp Delivery Settings

    Read WhatsApp Delivery Settings (including templates)

    Organizations

    PingOne uses an organization-based model to define tenant accounts and their related entities. The organization is the top-level identifier. It defines your entire enterprise within the PingOne platform. The organizations endpoints provide functions to read organizations resources.

    Learn more about organizations in Introduction to PingOne, in the PingOne Admin Guide.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    organizations ORGANIZATION.CREATED
    organizations ORGANIZATION.UPDATED
    organizations ORGANIZATION.DELETED

    Organzations data model

    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The time the resource was created.
    description String Optional Mutable The description of the organization.
    id String Required Immutable The resource’s unique identifier.
    name String Required Mutable The organization name, which must be provided and must be unique among all organizations in PingOne.
    billingConnections.id String Required Immutable The list of the BillingConnection resource IDs for the organization.
    type String Required Mutable The organization type. If the organization has any paid licenses, the type property value is set to PAID. Otherwise, the property value is set to TRIAL.
    updatedAt Date N/A Read-only The time the resource was last updated.

    Response codes

    Code Message
    200 Successful operation.
    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.

    Read All Organizations

    Read One Organization

    Populations

    In PingOne, populations are similar to an organizational unit (OU) and are used to simplify user and policy management within a given environment. For example, you can create a population for similar types of users, such as those in a particular region or job function, and assign those users a unique password policy.

    The /environments/{{envID}}/populations endpoint provides operations to create, read, update, and delete population resources within a specified environment.

    Before you can create users, you must have at least one existing population. When you create a user, you can assign them to a specified population. If you do not specify a population, PingOne adds the new user to the default population. You can configure any population to be the default population, either at the time of creation or at a later time.

    Individual users cannot belong to more than one population within a PingOne environment. However, you can move users to a different population within the existing environment.

    Learn more in Populations, in the PingOne Admin Guide.

    Populations data model

    Property Type Required? Mutable? Description
    alternatveIdentifiers String[] Optional Mutable Alternative identifiers that can be used to search for populations besides name.
    createdAt Date N/A Read-only The time the resource was created.
    default String Required Mutable The population to use as the default population for the environment. Only one population per environment can be the default. New users are assigned to the default population if it exists, and the Population ID is not provided in the Create User request.
    description String Optional Mutable The description of the population.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the population.
    id String Required* Immutable The resource’s unique identifier. *This is optional if you're setting PingOne as the default identity provider using PUT Update Population Default IdP.
    name String Required Mutable The population name, which must be provided and must be unique within an environment.
    preferredLanguage String Optional Mutable The language locale for the population. If absent, the environment default is used.
    updatedAt Date N/A Read-only The time the resource was last updated.
    userCount Integer N/A Read-only The number of users that belong to the population.
    passwordPolicy Object Optional Mutable The object reference to the password policy resource.
    passwordPolicy.id String Optional Immutable The ID of the password policy that is used for this population. If absent, the environment's default is used.
    theme Object Optional Mutable The object reference to the theme resource.
    theme.id String Optional Immutable The ID of the theme to use for the population. If absent, the environment's default is used.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    populations POPULATION.CREATED
    populations POPULATION.UPDATED
    populations POPULATION.DELETED

    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.
    404 The requested resource was not found.

    Create Population

    Update Population

    Read All Populations

    Delete Population

    Read One Population

    Read One Population Default IdP

    Update Population Default IdP

    Resources

    A resource entity in PingOne can be one of the following types: OPENID_CONNECT, PING_ONE_API, or CUSTOM. Only the CUSTOM resource type can be created. The OPENID_CONNECT type specifies the built-in platform resource for OpenID Connect. The PING_ONE_API type specifies the built-in platform resource for PingOne. When you define an application in PingOne and specify its resource grant, you identify the protected endpoints that users can access when they sign on to that application.

    For custom resources, the Resources service models external resource servers that use PingOne to protect their APIs. The custom resource is the audience of access tokens generated by PingOne. For example, an application called Photo Archive uses a resource grant to the server, https://api.photoarchive.com, that provides APIs for users to interact with their photos. You can use the PingOne resources service to define the https://api.photoarchive.com as a custom resource and specify the scopes (permissions) that users get from authenticating and receiving an access token. In this scenario, when a user signs on, the PingOne authorization server returns an access token, giving the user permissions associated with the custom resource, such as permission:view-photos, permission:upload-photos, permission:edit-photos, or permission:delete-photos.

    You need the Environment Admin or the Client Application Developer roles to perform operations on resources.

    Resources data model

    Property Type Required? Mutable? Description
    accessTokenValiditySeconds Integer Required Mutable The number of seconds that the access token is valid. If a value is not specified, the default is 3600. The minimum value is 300 seconds (5 minutes); the maximum value is 2592000 seconds (30 days).
    applicationPermissionsSettings Object Optional Mutable An object that specifies whether to add application permissions to access tokens generated by PingOne.
    applicationPermissionsSettings.claimEnabled Boolean Optional Mutable A setting to enable application permission claims in the access token. If this property is omitted, the value is set to false.
    audience String Required Mutable A URL without a fragment or "@ObjectName" and must not contain "pingone" or "pingidentity" (for example, https://api.myresource.com). If a URL is not specified, the resource name is used. The value that you set here is returned in the audience claim in the token. For more information, see Token Introspection (Resource ID and Secret).
    createdAt Date N/A Read only The time the resource was created.
    description String Optional Mutable Description of the resource.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.
    id String Required Immutable The resource’s unique identifier.
    name String Required Immutable The resource name, which must be provided and must be unique within an environment.
    introspectEndpointAuthMethod String Required Mutable The authentication methods supported by the token endpoint. Options are NONE, CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, and PRIVATE_KEY_JWT. Applicable only to custom resources.
    type String Required Mutable The type of resource. Options are OPENID_CONNECT, PING_ONE_API, and CUSTOM. Only the CUSTOM resource type can be created. OPENID_CONNECT specifies the built-in platform resource for OpenID Connect. PING_ONE_API specifies the built-in platform resource for PingOne.
    updatedAt Date N/A Read only The time the resource was last updated.

    Resources core attribute data model

    Property Type Required? Mutable? Description
    sub String Required Mutable The core claim for the new resource. The default value is ${user.id}.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    resources RESOURCE.CREATED
    resources RESOURCE.UPDATED
    resources RESOURCE.DELETED

    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.
    404 The requested resource was not found.

    Resource Operations

    The /resources endpoint provides operations to create, read, update, and delete resource entities. The examples that follow show common actions to find and manage resources entities.

    You need the Environment Admin or the Client Application Developer roles to perform operations on resources entities.

    Create Resource

    Read All Resources

    Read One Resource

    Update Resource

    Delete Resource

    Resource Scopes

    Resources have scopes, and applications can request an access token that is associated with specific scopes when the token is granted. The endpoint enforces access through the encoded representation of the scopes in the access token. The endpoint decodes the token to determine the permissions allowed for the application.

    Scopes define the permissions for an application or a user. The scopes associated with the actor determine the resources that the actor can access. For example, an actor with a PingOne API resource access token that includes the p1:read:user scope has read access to view their own user resource data.

    Custom resource scopes

    You can define a custom resource, such as https://api.photos.com that has associated scopes, such as edit:photos, upload:photos, and delete:photos. The POST {{apiPath}}/environments/{{envID}}/resources/{{resourceID}}/scopes endpoint defines a new scope associated with the https://api.photos.com custom resource, which is identified by the {{resourceID}} variable in the request URL. The new custom scope grants actors access to otherwise resources on the https://api.photos.com custom resource server.

    PingOne resource scopes

    The PingOne API is one of two predefined resources in the PingOne platform. The PingOne API resource has several predefined self-management scopes associated with it that grant users access to PingOne resources. The self-management scopes specified in an authorization request, such as p1:update:user or p1:reset:userPassword identify the resources that end user can access to perform self-management actions. For a list of PingOne API self-management scopes, see PingOne self-management scopes.

    Resource scopes and access tokens

    Scopes from one resource, such as PingOne API (https://api.pingone.com), cannot be included in an access token with scopes from another custom resource such as https://api.photos.com. However, you can include the platform's predefined OpenID Connect resource (openid) scopes in an access token along with scopes from another resource. For more information about OpenID Connect scopes, see OpenID Connect (OIDC) scopes.

    PingOne access control scopes

    Most PingOne API scopes cannot be modified. However, user scopes such as the p1:read:user and p1:update:user can be modified to add or remove user schema attributes. In addition, PingOne supports custom PingOne access control scopes that use the syntax p1:read:user:{suffix} and p1:update:user:{suffix} for these two platform scopes. These custom PingOne scopes designate a specific set of user schema attributes, which is often a subset of attributes that the user is allowed to read or update. For example, a p1:update:user:email-only scope could remove all other user schema attributes except the user's email address. A user with this scope could update only their email address. All other visible attributes would not allow modification. For more information, see Access services through scopes and roles.

    Scopes and authorize requests

    The following authorization request shows a authorization_code grant type, in which the p1:read:user scope is specified, ensuring that this permission is encoded into the returned access token:

    curl --request GET \
  --url 'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=p1:read:user&acr_values=Single_Factor'

    You can specify more than one scope (from the same resource or from the openid resource) in the authorization request by adding additional scope names separated by spaces.

    curl --request GET \
  --url 'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=p1:read:user p1:update:user:email-only p1:reset:userPassword&acr_values=Single_Factor'

    The examples that follow show common actions to find and manage resource scope entities. You need the Client Application Developer role to perform operations on resources entities.

    For more information about scopes, see Configure access through scopes and roles.

    Adding mapped claims to an ID token or userinfo

    If the resource's type property is OPENID_CONNECT, you can add scopes to the resource that include custom mapped claims. The mappedClaims property in the POST {{apiPath}}/environments/{{envID}}/resources/{{openidResourceID}}/scopes request specifies the IDs of the resource attributes to add to the scope.

    For example, the OpenID Connect profile scope includes the following predefined profile claims: name, given_name, family_name, middle_name, nickname, preferred_username, picture, zoneinfo, locale, updated_at, profile, website, gender, and birthdate. If you add the ID for a predefined claim that already exists in the scope, such as given_name, it is ignored in the response. However, if you add the predefined phone_number attribute to the profile scope, the ID for the phone_number attribute is returned in the mappedClaims property in the response.

        "mappedClaims": [
        "579dc6f8-bf83-43ae-816c-324506b5de21"
    ],

    You can add custom claims to an OpenID Connect scope that you define using the Create Resource Attribute endpoint. The create request can include the idToken and userInfo properties to designate (globally) whether the claim should be added to the ID token and returned by the userinfo endpoint. You can specify that the idToken anduserInfo properties are both true, one can be true and the other false, but both properties cannot be set to false.

    Resource scopes data model

    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The time the resource was created.
    description String Optional Mutable The description of the scope.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the resource.
    id String Required Immutable The scope resource’s unique identifier.
    mappedClaims String[] Optional Mutable A list of custom resource attribute IDs. This property applies only for the resource with its type property set to OPENID_CONNECT. Moreover, this property does not display predefined OpenID Connect (OIDC) mappings, such as the email claim in the OIDC email scope or the name claim in the profile scope. You can create custom attributes, and these custom attributes can be added to mappedClaims and will display in the response.
    name String Required Mutable The resource scope name. Scope names are only unique for the resource and not the environment.
    resource.id String Required Immutable The unique identifier of the resource entity associated with the scope.
    schemaAttributes String[] Optional Mutable The user schema attributes that can be read or updated for the specified PingOne access control scope. The value is an array of schema attribute paths (such as username, name.given, shirtSize) that the scope controls. This property is supported only for the p1:read:user, p1:update:user and p1:read:user:{suffix} and p1:update:user:{suffix} scopes. No other PingOne platform scopes allow this behavior. Any attributes not listed in the attribute array are excluded from the read or update action. The wildcard path (*) in the array includes all attributes and cannot be used in conjunction with any other user schema attribute paths.
    updatedAt Date N/A Read-only The time the resource was last updated.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    resources SCOPE.CREATED
    resources SCOPE.UPDATED
    resources SCOPE.DELETED

    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.
    404 The requested resource was not found.

    Create Custom resource scope

    Create PingOne access control scope

    Create OpenID Connect resource scope

    Read All Scopes (Resource)

    Read One Scope

    Update Scope

    Update PingOne access control scope

    Delete Scope

    Resource Attributes

    PingOne access tokens are signed JWTs (JSON Web Tokens) that include identity claims about and attributes of the requestor, usually a user identity. The resource attributes service lets you customize the content of access tokens by adding custom attributes and their values. This is a great way to convey additional information about the user to applications. Custom attributes have a cumulative length constraint of 16 Kb. See Custom attributes in Schemas for more information.

    Resource attributes are essentially custom identity claims associated with a resource. For example, suppose the clothing.preferences resource with scope sizes provides "clothing size" user claims in the token. By default, the sizes scope does not include a t-shirt size user claim. To include the user.tshirtSize user attribute as a user claim in the token, a resource attribute entity can be created that associates the tshirtSize attribute with the clothing.preferences resource. Then, for token requests to clothing.preferences with scope sizes, the tshirtSize user claim is included in the token. If the attribute is multiValued, then the claim will be an array of values. The following diagram shows the workflow:

    Resource attributes custom identity claims

    For information about an access token's core claims, see Access token claims. A token's core identity claims cannot be modified or deleted.

    Advanced resource attribute mapping

    You can use PingOne's expression language for advanced attribute mappings of a custom resource or the OpenID Connect resource. The supported expression language is an augmentation of SpEL. SpEL is a powerful expression language used for querying and manipulating an object graph at runtime.

    Resource attributes data model

    Property Type Required? Mutable? Description
    idToken Boolean Optional Mutable A boolean that specifies whether the attribute mapping should be available in the ID Token. This property is applicable only when the application's protocol property is OPENID_CONNECT. If omitted, the default is true. Note that the idToken and userInfo properties cannot both be set to false. At least one of these properties must have a value of true.
    userInfo Boolean Optional Mutable A boolean that specifies whether the attribute mapping should be available through the /as/userinfo endpoint. This property is applicable only when the application's protocol property is OPENID_CONNECT. If omitted, the default is true. Note that the idToken and userInfo properties cannot both be set to false. At least one of these properties must have a value of true.
    name String Required Mutable A string that specifies the name of the custom resource attribute to be included in the access token. The following are reserved names and cannot be used. These reserved names are applicable only when the resource's type property is OPENID_CONNECT:
    • acr
    • amr
    • aud
    • auth_time
    • client_id
    • env
    • exp
    • iat
    • iss
    • jti
    • org
    • p1.* (any name starting with the p1. prefix)
    • scope
    • sid
    • sub
    type String Optional Read-only A string that specifies the type of resource attribute. Options are:
    • CORE: The claim is required and cannot not be removed.
    • CUSTOM: The claim is not a CORE attribute. All created attributes are of this type.
    • PREDEFINED: A designation for predefined OIDC resource attributes such as given_name. These attributes cannot be removed; however, they can be modified.
    value String Required Mutable A string that specifies the value of the custom resource attribute. This value can be a placeholder that references an attribute in the user schema, expressed as “${user.path.to.value}”, or it can be a static string. Placeholders must be valid, enabled attributes in the environment’s user schema. Examples fo valid values are: “${user.email}”, “${user.name.family}”, and “myClaimValueString”.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    resources ATTRIBUTE.CREATED
    resources ATTRIBUTE.UPDATED
    resources ATTRIBUTE.DELETED

    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.
    404 The requested resource was not found.

    Create Resource Attribute

    Read All Resource Attributes

    Read One Resource Attribute

    Update Resource Attribute

    Delete Resource Attribute

    Resource Secret

    The client secret endpoint is available to users or worker resources only if they have a superset of the resource's role assignments.

    Access to the resource's client secret is restricted based on the accessing user's or resource's role assignments. For example, if a client has the Environment Admin role, an actor with an Identity Admin role cannot see the client secret. This restriction addresses privilege escalation issues by preventing the Identity Admin user from doing things with the client that the Identity Admin role assignment does not allow.

    Best practices

    • Do not store a resource's client secret in applications that are publicly available.

    • For security purposes, regenerate client secrets regularly.

    • If you suspect a resource's client secret has been compromised, generate a new client secret immediately.

    Resource client secret data model

    Property Type Required? Mutable? Description
    environment.id String Read-only The environment associated with the resource.
    previous Object Optional Read only An object that specifies the resource's previous secret, when it expires, and when it was last used.
    previous.secret String N/A Read only A string that specifies the resource's previous secret. This property is returned in the response if the previous secret is not expired.
    previous.expiresAt Timestamp Optional Read only A timestamp that specifies how long this secret is saved (and can be used) before it expires. Supported time range is 1 minute to 30 days.
    previous.lastUsed Timestamp Optional Read only A timestamp that specifies when the previous secret was last used.
    secret String N/A Read-only An auto-generated resource client secret. Possible characters are a-z, A-Z, 0-9, -, ., _, ~. The secret has a minimum length of 64 characters per SHA-512 requirements when using the HS512 algorithm to sign ID tokens using the secret as the key.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    resources SECRET.UPDATED
    resources SECRET.READ

    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.
    404 The requested resource was not found.

    Create Resource Client Secret

    Read Resource Client Secret

    Delete Previous Resource Client Secret

    Application Resources

    The PingOne Authorize {{apiPath}}/environments/{{envID}}/resources/{{resourceID}}/applicationResources endpoint provides operations to create, read, update, and delete application resources in PingOne.

    API application resources data model

    Property Type? Required? Mutable? Description
    description String Optional Mutable The application resource's description.
    id String N/A Read only The resource's unique identifier.
    name String Required Mutable The application resource name. The name value must be unique.
    parent Object N/A Read only The application resource's parent.
    parent.type String N/A Read only The application resource's parent type. Options are PING_ONE_RESOURCE.
    parent.id String N/A Read only The application resource's parent 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.

    Create Application Resource

    Read All Application Resources

    Read One Application Resource

    Update Application Resource

    Delete Application Resource

    Application Resources Permissions

    The PingOne Authorize {{apiPath}}/environments/{{envID}}/resources/{{resourceID}}/applicationPermissions endpoint provides operations to read application resource permissions on the specified PingOne resource identified by its ID in the request URL.

    Application resources permissions data model

    Property Type? Required? Mutable? Description
    action String Required Mutable The action associated with this permission.
    description String Optional Mutable The resource's description.
    id String N/A Read only The resource's unique identifier.
    key String N/A Read only The resource.name:action pair of the permission.
    resource Object N/A Read only An object that identifies the associated application resource.
    resource.id String N/A Read only The ID for the associated application resource.
    resource.name String N/A Read only The name of the associated application resource.
    resourceServer.id String N/A Read only The ID for the associated application resource server.
    resourceServer.environment.id String N/A Read only The ID for the environment associated with the application resource server.

    Response codes

    Code Message
    200 Successful operation.
    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.

    Read Application Permissions

    Roles Management

    The ability to perform an action in PingOne is determined by Role-Based Access Control (RBAC). For example, when you initiate a request to a PingOne endpoint, you must have the role required by the endpoint to execute the request. You'll notice that our endpoint documentation uses icons to indicate the role or roles needed to access the endpoint (see Read All Built-in Admin Roles for an example).

    You can assign a PingOne role to:

    • Users, PingOne admins, or (for custom roles) groups.

    • PingOne Worker Apps.

    • PingOne Gateways for PingFederate. Only gateways having a type property of PING_FEDERATE can be assigned a role. See Gateway Role Assignments for more information.

    Users who aren't an admin or Client Application Developer cannot be assigned a role, so have no access to the APIs, nor permissions to execute actions on behalf of another user.

    When assigning admin roles, you cannot assign roles that you do not have yourself, with the following exceptions:

    • You can assign the read-only variants of built-in roles that are assigned to you.

    • You can assign custom roles that have been configured to allow assignment by a role that's assigned to you.

    As a best practice, assign the minimum role or roles needed for the admin to perform their tasks. See Assigning a user role for more information.

    PingOne supports the following types of roles:

    • Built-in Admin Roles

      These roles are predefined in the platform. The permissions associated with PingOne roles are managed by the platform. Common PingOne roles are Organization Admin, Environment Admin, Identity Data Admin, and Client Application Developer.

    • Custom Admin Roles

      These roles are environment-level resources that consist of a set of permissions that can be edited by administrators. A custom role can be assigned to a user or admin group for a specific scope.

    • PingOne Authorize Application Roles

      These roles are part of the PingOne Authorize capability. You must have the PingOne Authorize product capability activated in your license to access these endpoints. Application roles define custom roles and permissions within PingOne to protect external application resources.

    Built-in Admin Roles

    These roles and the associated permissions are predefined (built-in) for PingOne:

    Role Icon Abbr. Can Assign
    Organization Admin Organization Admin role ORG Environment Admin
    Environment Admin Environment Admin role ENV All roles except Organization Admin
    Identity Data Admin Identity Data Admin role IDA Identity Data Admin, Identity Data Read-Only Admin
    DaVinci Admin DaVinci Admin role DVA DaVinci Admin, DaVinci Read-Only Admin
    Custom Role Admin Custom Role Admin role ROLE None
    Application Owner Application Owner role APP-O None
    Identity Data Read-Only Admin Identity Data Read Only role IDA-R None
    Configuration Read-Only Admin Configuration Read Only role CFA-R None
    DaVinci Read-Only Admin DaVinci Admin Read Only role DVA-R None
    Client Application Developer Client Application Developer role APP None
    Advanced Identity Cloud

    These roles and the associated permissions are predefined (built-in) for PingOne support of Advanced Identity Cloud:

    Role Abbr. Can Assign
    Advanced Identity Cloud Super Admin AIC-SUPER Advanced Identity Cloud Super Admin, Advanced Identity Cloud Tenant Admin
    Advanced Identity Cloud Tenant Admin AIC-TENANT None

    Roles and Permissions

    See PingOne Role Permissions for the PingOne roles and their permissions.

    See PingFederate SSO admin permissions for the applicable PingFederate roles.

    Automatic role assignments

    Role assignments determine access to PingOne APIs. When an application or user creates a new PingOne resource over which roles can be assigned, they are assigned all possible roles that can be assigned for the environment or population. For example, if an actor creates a new environment, the actor receives the Environment Admin, Identity Data Admin, and the Client Application Developer roles over that new environment. If the actor already has an existing organization-level Environment Admin role, the Environment Admin role would not be assigned again to the actor. Likewise, if the actor creates a new population, the actor receives the Identity Data Admin role automatically (unless the actor already has that assigned role).

    Users and applications cannot create actors that have more privileges than the user or application itself. For example, to create a user or an application that has Environment Admin privileges, the actor assigning roles must also have Environment Admin privileges. The actor (user or application) assigning roles must have the permissions that they are trying to assign. The requesting user or application must have the same (or broader) role assignments as the target actor’s role assignments.

    When creating PingOne resources, the following roles are assigned to the actor automatically when these PingOne entities are created:

    • Environments

      Environment Admin: Assigned for the created environment at the environment level, if the actor does not already have the Environment Admin role at the parent organization level.

      Identity Data Admin: Assigned for the created environment at the environment level.

      Client Application Developer: Assigned for the created environment at the environment level.

    • Populations

      Identity Data Admin: Assigned for the created population at the population level, if the actor does not already have the Identity Data Admin role at the parent environment level.

    Roles data model

    Property Type Required? Mutable? Description
    actor.id String Required Immutable The ID of the actor.
    actor.environmentId String Required Immutable The ID of the environment in which the actor exists.
    actor.type String Required Immutable The type of the actor. Options are users and clients.
    description String Optional Immutable The description of the resource.
    environment.id String N/A Read-only The environment resource’s unique identifier associated with the resource.
    id String N/A Read-only The resource’s unique identifier.
    name String Required Immutable The resource name.
    role.applicableTo String Required Immutable The scope types to which the role can be applied. Options are ORGANIZATION, ENVIRONMENT, and POPULATION.
    role.description String Optional Mutable The description of the role.
    role.id String N/A Read-only The ID of the role.
    role.permissions String Required Immutable The set of permissions assigned to the role.
    role.permissions.classifier String Required Immutable The resource for which the permission is applicable.
    role.permissions.description String Optional Mutable The description of what the permission enables for the role.
    role.permissions.id String Optional Mutable The ID of a permission associated with this role.
    role.scope.id String Required Mutable A string that specifies the ID of the role assignment scope.
    role.scope.type String Required Immutable The type of resource defining the scope of the role assignment. Options are PLATFORM, ORGANIZATION, ENVIRONMENT, POPULATION, and ACTOR.
    type String Required Immutable The type of resource. Options are PLATFORM and CUSTOM.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    roles ROLE.CREATED
    roles ROLE.UPDATED
    roles ROLE.DELETED

    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.

    Read All Built-in Admin Roles

    Read One Built-in Admin Role

    Custom Admin Roles

    A custom admin role is an environment-level resource that consists of a set of permissions that can be edited by administrators. A custom role can be assigned to an individual user, group, worker application, or PingFederate Gateway for a specific jurisdiction (scope). The jurisdiction can be at the organization level, environment level, or population level. The role assignment also specifies the assignee, the actor who is assigned the role for the designated jurisdiction.

    Custom admin role assignments

    Role assignments for custom roles follow these common scenarios:

    1. The admin assigns the custom role to someone in the same environment because they have that custom role.

    2. The admin assigns a custom role to someone in the same environment because the role they have is specified in the canBeAssignedBy attribute of the custom role.

    3. The admin assigns a custom role to someone in a different environment because the role and actor exist in a different environment. This is possible because the admin assigning has scope (juristiction) over the different environment through a PingOne role, which is specified in the custom role's canBeAssignedBy property.

    To summarize these scenarios, the actor can assign a custom role to others for a specific jurisdiction only if one or more of the following conditions are true:

    • The actor already has the same role for the jurisdiction or parent jurisdiction.

    • The actor has a role that is specified in the canBeAssignedBy property of the custom role for the jurisdiction or parent jurisdiction.

    For additional examples on assigning custom roles, see Custom Roles Scenarios In the PingOne Admin Guide.

    Custom admin role restrictions

    There are additional restrictions for using custom admin roles (these restrictions do not apply to the built-in roles).

    • Custom admin roles are not supported for PingOne Davinci at this time.

    • Custom admin roles can only be assigned at the organization level to users, groups, applications, and gateways in the administrators environment.

    • Custom roles created in any non-administrators environment can only be assigned against resources within that environment (or the entire environment).

    Roles and Permissions

    See PingOne Role Permissions for the PingOne roles and their permissions.

    See PingOne Permissions by Identifier for all permissions.

    Filtering data

    The Read All Custom Admin Roles request supports SCIM filtering expressions. The query filter can be appended to the request URL to fine-tune the response data. For example, the following filter returns only the custom roles:

    GET {{apiPath}}/environment/{{envID}}/roles?filter=%28type+eq+%22CUSTOM%22%29

    These SCIM operators can be applied to the following attributes:

    eq (equal to)

    Supported attributes: type

    Custom administrator roles data model

    Property Type Required? Mutable? Description
    applicableTo String[] Optional Immutable The scope types to which the role can be applied. Options are ORGANIZATION, ENVIRONMENT, and POPULATION.
    canAssign Object Read only Immutable A relationship that specifies if an actor is assigned the current custom role for a jurisdiction, then the actor can assign any of this set of roles to another actor for the same jurisdiction or sub-jurisdiction. This capability is dreived from the canBeAssignedBy property.
    canBeAssignedBy Object Required Mutable A relationship that determines whether a user assigned to one of this set of roles for a jurisdiction can assign the current custom role to another user for the same jurisdiction or sub-jurisdiction.
    description String Optional Mmutable The description of the role.
    environment.id String N/A Read-only The environment resource’s unique identifier associated with the resource.
    id String N/A Read-only The resource’s unique identifier.
    name String Required Mutable The role name.
    permissions String Required Mutable The set of permissions assigned to the role.
    type String N/A Read only A value that indicates whether the role is a built-in role or a custom role. Options are PLATFORM and CUSTOM.

    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.

    Create Custom Admin Role

    Read All Custom Admin Roles

    Read One Custom Admin Role

    Update Custom Admin Role

    Delete Custom Admin Role

    Sessions

    The Sessions service enables you to create and manage sessions for either specified or unspecified (anonymous) users. Anonymous sessions are short-lived sessions that are created while the user authentication process occurs.

    Session token cookies can be handled through a browser or, for non-browser authentication flows, in the same manner as a browser, by saving the cookies when returned in an HTTP response from PingOne, and including the cookies on subsequent requests. Whenever possible, use the cookie handling features of the development platform, HTTP client library, or both.

    See User Sessions for interfaces on the Users endpoint, and Best Practices: Session Management for best practices.

    PingOne sessions have the following characteristics:

    • Sessions are created (always) when a user signs on through PingOne and an existing session does not exist for the client.

    • A session is tied to all applications that the user signed into on that client (browser).

    • Sessions are identified through a session cookie when a user signs on (calls the authorize endpoint).

    • Sessions are associated with an entire SSO session, which includes all applications using the session.

    • A sign-off action terminates the entire SSO session and logs the user out of all applications using the session.

    Sign-off and sessions

    When the GET /{{envID}}/as/signoff endpoint is invoked, the sign-off operation ends the user's SSO session, which signs them out of all applications using that session. This endpoint can take an id_token_hint parameter to provide information about the user's current authenticated session. The session token must be an id_token type to complete the sign-off action successfully.

    For more information, see Signoff in the PingOne Platform API Reference.

    Token revocation and sessions

    When the POST /{{envID}}/as/revoke endpoint is invoked, the token revocation operation revokes the specified token, but leaves the SSO session intact. This endpoint revokes tokens of type access_token and refresh_token. It does not support revocation of tokens of type id_token.

    The tokens to be revoked must be an access_token or refresh_token for a custom resource. Tokens issued for the PingOne API resource may not be revoked.

    For more information, see Token Revocation in the PingOne Platform API Reference.

    Session tokens and PingOne flows

    For PingOne flows, the session token cookies establish the user's authentication session, and maintain the flow session, allowing the flow to redirect back to the authorization server to get the token.

    For flows started through the Read Flow endpoint, a session token cookie is set only after the identity of the user has been partially established. For example, if the sign-on policy specifies identifier first and MFA actions, the cookie is set after the user is identified through a user lookup action, and the user supplies the correct password. For a flow initiated in a browser that already has a valid session token cookie, calling the flow requires the session token cookie, which can be passed in as a request header.

    Typical authentication flow for the Sessions service

    Typical sessions authentication flow

    Session data model

    Property Type Required? Mutable? Description
    activeAt Date Required Mutable The time of last user activity for this session (such as, completing a flow, or an application activity like validating a token).
    browser.name String N/A Read-only The name of the browser.
    browser.version String N/A Read-only The version of the browser.
    createdAt Date N/A Read-only The time the resource was created.
    device.type String N/A Read-only The type of remote device.
    environment.id String N/A Read-only The UUID for the environment.
    expiresAt Date N/A Read-only The date and time the session will expire, based on the values for ‘idleTimeoutInMinutes’ and activeAt.
    id String N/A Read-only The unique identifier for the session.
    idleTimeoutInMinutes Integer Optional (for POST) Mutable This is required for a PUT operation. The maximum idle time in minutes after which the session will become invald. This is used to evaluate expiresAt, based on the activeAt value. For POST operations to create a session, the idle timeout for an anonymous session defaults to 30 minutes (the maximum for anonymous sessions). The idle timeout for user-specified sessions defaults to 30 days, with a maximum of 365 days. The minimum idle timeout value for any session is 1 minute. Sessions are automatically removed after the idle timeout.
    lastSignOn Object Required Mutable Contains information about the most recent sign-on events. Null if the user isn't identified.
    lastSignOn.at String N/A Read-only The last time the user signed on using one or more authenticators.
    lastSignOn.remoteIp String Required Mutable The IP address of the remote device used during the last sign-on.
    lastSignOn.policy Object N/A Read-only The Flow Policy UUID.
    lastSignOn.policy.id String N/A Read-only The Policy associated with the last completed sign-on by the lastSignOn.authenticator.
    lastSignOn.policy.type String N/A Read-only This is either DAVINCI or PINGONE.
    lastSignOn.authenticators String[] Required Mutable The authenticators used during the last sign-on.
    lastSignOn.withAuthenticator Map Required Mutable Details for all authenticators used in a session, and each authenticator’s most recent sign-on activity.
    lastSignOn.withAuthenticator.
    authenticator    		 String Required Mutable The name of the authenticator. The names are generally Authentication Method Reference (AMR) values (such as, pwd, mfa). Values other than AMR values are also supported. The values must be lowercase alpha characters with a maximum length of 10.
    lastSignOn.withAuthenticator.
    authenticator.at    		 Date Required Mutable The last time the authenticator was used for sign-on.
    lastSignOn.withAuthenticator.
    authenticator.policy    		 Object Required Mutable The Flow Policy UUID.
    lastSignOn.withAuthenticator.
    authenticator.policy.id    		 String Required Mutable The Policy associated with the last completed sign-on by the lastSignOn.authenticator. If lastSignOn.withAuthenticator.authenticator.policy.type is PINGONE, this value is a UUID. If lastSignOn.withAuthenticator.authenticator.policy.type is DAVINCI, this value must be 32 lowercase HEX characters.
    lastSignOn.withAuthenticator.
    authenticator.policy.type    		 String Required Mutable This is either DAVINCI or PINGONE.
    locations Object[] N/A Read-only Contains the attributes identifying the user location. Only the last 5 locations are maintained.
    location.at Date N/A Read-only The last time the user signed on.
    location.remoteIp String N/A Read-only The IP address of the remote device used during the last sign-on.
    location.city String N/A Read-only The city resolved from the IP address.
    location.state String N/A Read-only The state resolved from the IP address.
    location.region String N/A Read-only The region resolved from the IP address.
    location.country String N/A Read-only The country resolved from the IP address.
    operatingSystem.name String N/A Read-only The name of the operating system.
    operatingSystem.version String N/A Read-only The operating system version.
    remoteIp String Optional Mutable IP address used to perform any activity that extends the session (for activities other than sign-on). If specified, this value is appended to the location history as location.remoteIp, with the activeAt value as the value of location.at. This setting cannot be retrieved in a JSON response directly, as it's incorporated into location history.
    token String Optional Mutable Required for Update Session By Session Token. The token associated with the session for use with the session token cookie. For a POST operation, you need to specify this if you intend to use any of the /me (Session Token) endpoints. This is a UUID value, and must be unique to the environment. For Update Session By ID, if the session token is specified in the request, it is discarded. The session token can be changed only using Update Session By Session Token.
    user.id String Optional Immutable The UUID for the user associated with the session. This can be null until authentication is completed. Once set, this value can't be changed. If user.Id is specified for a session, you need to supply authenticator information in the lastSignOn object. If user.id isn't specified, the lastSignOn object is null, and any values assigned to the lastSignOn object are ignored.
    userAgent String Required Mutable The raw user agent string from the user agent header of the request that initiated the flow.

    Create Session

    Reset Authentication Session by Session ID

    Reset Authentication Session by Session Token

    Read Session By ID

    Read Session By Session Token

    Update Session By ID

    Update Session By Session Token

    Delete Session By ID

    Delete Session By Session Token

    Sign-On Policies

    Sign-on policies (identified in the PingOne UI as "Authentication Policy") determine the account authentication flow users must complete to access applications secured by PingOne services.

    Sign-on policies are defined by their associated actions. For example, the LOGIN action prompts users for a username and password. The MULTI_FACTOR_AUTHENTICATION action prompts users to complete a second authentication action, such as entering a one-time passcode received on a registered device or accepting a push confirmation on a registered native device.

    For more information about sign-on policies, see Authentication policies in the PingOne Admin Guide.

    An application's sign-on policy determines the flow states and the corresponding actions required to complete an authentication workflow. The following diagram shows the PingOne platform sign-on policy selection logic:

    Sign-on policy selection logic

    When the authentication workflow begins, the flow gets the list of sign-on policies assigned to the application and evaluates the policy conditions that must be met to complete sign on. The sign-on policy evaluation logic is shown in the diagram below:

    Sign-on policy evaluation logic

    Sign-on policies

    The /environments/{{envID}}/signOnPolicies endpoint provides operations to create, read, update, and delete sign-on policies.

    For more information, see Sign-On Policies.

    Sign-on policy actions

    The /environments/{{envID}}/signOnPolicies/{{policyID}}/actions endpoint provides operations to create, read, update, and delete sign-on policy actions.

    For more information, see Sign-On Policy Actions.

    Sign-On Policies Operations

    The sign-on policies endpoints provide common operations to create and manage sign-on policies resources.

    You need the Environment Admin role to perform operations on sign-on policy resources.

    Sign-on policies data model
    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The time the resource was created.
    default Boolean Required Mutable Indicates whether this sign-on policy is the environment's default that is used by applications that do not have application-specific sign-on policy assignments. This property can only be set to true, in which case the isDefault property of all other sign-on policies are set to false.
    description String Optional Mutable The description of the sign-on policy.
    environment.id String Required Immutable The environment resource’s unique identifier associated with the sign-on policy.
    id String Required Immutable The sign-on policy resource’s unique identifier.
    name String Required Mutable Rhe resource name. The name must be unique within the environment, and can consist of either a string of alphanumeric letters, underscore, hyphen, period: ^[a-zA-Z0-9_.-]+$ or an absolute URI if the string contains a “:” character.
    updatedAt Date N/A Read-only The time the resource was last updated.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    signOnPolicies POLICY.CREATED
    signOnPolicies POLICY.UPDATED
    signOnPolicies POLICY.DELETED
    Response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    204 Successfully removed. No content.
    400 The request could not be completed.
    404 The requested resource was not found.

    Create Sign-On Policy

    Read All Sign-On Policies

    Read One Sign-On Policy

    Update Sign-On Policy

    Delete Sign-On Policy

    Sign-On Policy Actions

    Sign-on policy actions specify the particular sign-on action and the conditions that determine when the action is executed. PingOne supports the following sign-on policy actions:

    • LOGIN

      An action that prompts users for a username and password.

      If you're provisioning users from an external LDAP directory, see the userTypes parameter for the Gateway LDAP data model. For flow details, see Login action.

    • MULTI_FACTOR_AUTHENTICATION

      A two-step authentication method that prompts users to enter a one-time password received on a registered device or accept a push confirmation on a registered native device. For flow details, see Multi-factor (MFA) action.

    • IDENTIFIER_FIRST

      An action used to identify the user by username and determine the applicable authentication methods for this user. Identifier first flows do not result in a failed state. Any user that does not match a discovery rule will authenticate against PingOne. For flow details, see Identifier first action.

    • PROGRESSIVE_PROFILING

      An action to prompt users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data. For flow details, see Progressive profiling action.

    • IDENTITY_PROVIDER

      An action that bypasses the PingOne sign-on prompt and immediately redirects the user to an external identity provider's sign-on workflow to authenticate. For flow details, see Identity provider account confirmation.

    • AGREEMENT

      An action that enforces consent to an agreement.

    Sign-on policy action conditions

    PingOne sign-on policy actions support a policy condition language that allows both logical and data rules to construct a policy condition statement. Logical rules reflect the combined result of their contained rules. A logical rule can contain other logical rules or data rules. Data rules do not contain other rules; they are used for straightforward comparison.

    Policy condition logical rules

    There are three logical operations. The JSON operators for logical rule expressions are:

    • and

      Constructed as a JSON array (for example, "and":["{rule1}", "{rule2}"]). For this expression, all rules must be true to meet the condition.

    • or

      Constructed as a JSON array (for example, "or":["{rule1}", "{rule2}"]). For this expression, at least one rule must be true to meet the condition.

    • not

      Constructed as a JSON object (for example, "not":[{inner_rule}]). For this expression, the value must not be true to meet the condition.

    The following sample shows a condition statement that uses the not logical operation:

    "condition": {
   "not": {
        "ipRange": [
            "10.1.1.1/8",
            "10.0.0.0/8"
        ],
        "contains": "${flow.request.http.remoteIp}"
    }
}

    In this case, the sign-on policy associated with this condition prevents sign-on from devices that contain the remote IP address value specified by the variable ${flow.request.http.remoteIp} in the specified IP address ranges.

    The following sample shows a condition statement that uses the or logical operation to perform a data evaluation:

    "condition": {
    "or": [
        {
            "value": "${user.population.id}",
            "equals": "ae2245b4-a942-47ad-9c9c-f6be13c2266b"
        },
        {
            "value": "${user.population.id}",
            "equals": "b0f1e4af-e0d1-4677-900c-fec8a354b332"
        }
    ]
}

    The sign-on policy associated with this condition allows sign-on if the actor requesting access has a population ID value of ae2245b4-a942-47ad-9c9c-f6be13c2266b or b0f1e4af-e0d1-4677-900c-fec8a354b332 (or both).

    Policy condition data rules

    Data comparisons determine whether a given property value matches a second value or meets a specified threshold. A data comparison can be a one-to-one match using the equals operator:

    {
    "value": "${user.population.id}",
    "equals": "b0f1e4af-e0d1-4677-900c-fec8a354b332"
}

    A data comparison can also check whether a value has exceeded a specified maximum using the greater operator:

    {
  "secondsSince" : "${session.lastSignOn.withAuthenticator.mfa.at}",
  "greater" : 50400
}

    In this case, if the condition is met (the time since the last sign-on exceeds one hour), then the user can be directed to a specific authentication action, such as re-entering a password.

    Condition variables

    The following variables can be referenced in sign-on policy action conditions:

    Property Description
    ${session.lastSignOn.withAuthenticator.pwd.at} Specifies the last successful time the password authenticator was used for sign on.
    ${session.lastSignOn.withAuthenticator.mfa.at} Specifies the last successful time an MFA authenticator was used for sign on. Options are: email, sms, voice, authenticator, user, and applications.id.
    ${flow.request.http.remoteIp} Specifies the remote IP address of the request that initiated the flow.
    ${user.*} Specifies the user attribute used in the condition. Only string core, standard, and custom attributes are supported. For complex attribute types, you must reference the sub-attribute (${user.name.firstName}).
    ${conditions.geovelocity} Specifies that an authentication request requires MFA when a geovelocity anomaly is detected. The PingIntelligence platform analyzes location data and determines whether travel time between a user’s current login location and their previous login location is possible in the time frame that has elapsed since the previous login.
    ${conditions.ipRisk} Specifies that an authentication request requires MFA when the request comes from an IP address with a high risk score. The PingIntelligence platform collects and analyzes IP address data of authentication requests. An IP address is considered high risk if it may have recently been involved in malicious activities, such as DDos attacks, or spam activity. When the ipRisk condition is applied, the minScore and maxScore parameters defining the high risk score range must be supplied. Authentication requests with a risk score greater than minScore, and less than or equal tomaxScore require MFA.
    For example, if minScore is 80 and maxScore is 90:
    • An authentication request with risk score of 80 and below does not require MFA.
    • An authentication request with risk score in the range of 81 to 90 (inclusive) requires MFA.
    • An authentication request with risk score of 91 and above does not require MFA.
    The value set by the admin UI for minScore is 80, and for maxScore is 100. These are also the recommended values.
    ${conditions.anonymousNetwork} Specifies that an authentication request requires MFA when the request comes from an IP address detected as an anonymous network. The PingIntelligence platform analyzes IP address data of authentication requests. When the platform identifies an IP address as originating from an anonymous network such as an unknown VPN, proxy or anonymity communication tool such as Tor, it will invoke the MFA flow, with the exception of authentication requests originating from whitelisted IP addresses.

    Sign-on policy actions base data model
    Property Description
    conditions.ipRange A string that specifies the supported network IP addresses expressed as classless inter-domain routing (CIDR) strings.
    conditions.secondsSince An integer that specifies the maximum number of minutes to wait since the last sign on before prompting for a new sign-on action.
    environment.id A string that specifies the environment resource’s unique identifier associated with the sign-on policy.
    id A string that specifies the sign-on policy assignment resource’s unique identifier.
    priority An integer that specifies the order in which the policy referenced by this assignment is evaluated during an authentication flow relative to other policies. An assignment with a lower priority will be evaluated first. This is a required property.
    signOnPolicy.id A string that specifies the associated sign-on policy resource’s unique identifier.
    type A string that specifies the type of action. Options are: LOGIN, MULTI_FACTOR_AUTHENTICATION, IDENTIFIER_FIRST, and PROGRESSIVE_PROFILING.
    LOGIN action data model
    Property Description
    confirmIdentityProviderAttributes A boolean that specifies whether users must confirm data returned from an identity provider prior to registration. Users can modify the data and omit non-required attributes. Modified attributes are added to the user's profile during account creation. This is an optional property. If omitted, the default value is set to false.
    enforceLockoutForIdentityProviders A boolean that if set to true and if the user's account is locked (the account.canAuthenticate attribute is set to false), then social sign on with an external identity provider is prevented.
    newUserProvisioning Enables user entries existing outside of PingOne to be provisioned in PingDirectory during login, using an external integration solution (such as a Gateway).
    newUserProvisioning.gateways Allows a set of preconfigured gateways or userType pairs that are specified in the Gateway Management schema to determine how to find and migrate user entries existing in an external directory.
    newUserProvisioning.gateways.id A string referencing the UUID for the gateway.
    newUserProvisioning.gateways.type A string identifying the type of gateway. Currently, only LDAP is supported.
    newUserProvisioning.gateways.userType A reference to the ID of the userTypes configuration set on the gateway for user account migration`.
    newUserProvisioning.gateways.userType.id A string referencing the UUID of userType.
    recovery Specifies the account recovery options.
    recovery.enabled A boolean that specifies the enabled/disabled state of the account recovery action. The default is disabled when creating a new policy. When enabled, it allows the use of the forgot password flow.
    registration Specifies the account registration options.
    registration.enabled A boolean that specifies the enabled/disabled state of the policy action. The default is disabled when creating a new policy. When enabled, it allows the use of the new user registration flow. This attribute should be set to true when implementing the social login sign-on policy option.
    registration.external A string that specifies the link to the external identity provider's identity store. This property is set when the administrator chooses to have users register in an external identity store. This can be set only when the registration.enabled property is false. This cannot be used when registration.flowDefinition is enabled.
    registration.population.id A string that specifies the population ID associated with the newly registered user.
    registration.flowDefinition A reference to a flow definition to use for user registration rather than the registration logic provided by the action. This can only be set when registration.enabled is false. This cannot be used when registration.external is enabled.
    socialProviders[0].id An array of strings that specifies the IDs of the identity providers that can be used for the social login sign-on flow.
    MULTI_FACTOR_AUTHENTICATION action data model
    Property Description
    deviceAuthenticationPolicy.id The ID of the MFA policy that should be used. This parameter is optional. If it is omitted, the default MFA policy is used.
    noDeviceMode Optional parameter. A string that specifies the device mode for the MFA flow. Options are BYPASS to allow MFA without a specified device, or BLOCK to block the MFA flow if no device is specified. To use this configuration option, the authorize request must include a signed login_hint_token property. For more information, see Authorize (Non-redirect and MFA Only Flows). If the parameter is not provided, the default value is BLOCK.
    IDENTIFIER_FIRST action data model
    Property Description
    confirmIdentityProviderAttributes A boolean that specifies whether users must confirm data returned from an identity provider prior to registration. Users can modify the data and omit non-required attributes. Modified attributes are added to the user's profile during account creation. This is an optional property. If omitted, the default value is set to false.
    discoveryRules.condition The list of IDP discovery rules that are evaluated in order when no user is associated with the user identifier. The maximum number of rules is 100. The condition on which this identity provider is used to authenticate the user is expressed using the PingOne policy condition language, Constrained to the following format:
    {
    "value": "${user.username}",
    "contains": "{someValue}"
    }
    enforceLockoutForIdentityProviders A boolean that if set to true and if the user's account is locked (the account.canAuthenticate attribute is set to false), then social sign on with an external identity provider is prevented.
    identityProvider.id A string that specifies the identity provider that will be used to authenticate the user if the condition is matched.
    recovery Specifies the account recovery options.
    recovery.enabled A boolean that specifies the enabled/disabled state of the account recovery action. The default is disabled when creating a new policy. When enabled, it allows the use of the forgot password flow.
    registration Specifies the account registration options.
    registration.enabled A boolean that specifies the enabled/disabled state of the policy action. The default is disabled when creating a new policy. When enabled, it allows the use of the new user registration flow. This attribute should be set to true when implementing the social login sign-on policy option.
    registration.external.href A string that specifies the link to the external identity provider's identity store. This property is set when the administrator chooses to have users register in an external identity store. This attribute can be set only when the registration.enabled property is set to false.
    registration.population.id A string that specifies the population ID associated with the newly registered user.
    socialProviders[0].id An array of strings that specifies the IDs of the identity providers that can be used for the social login sign-on flow.
    PROGRESSIVE_PROFILING action data model
    Property Description
    attributes.name A string that specifies the name and path of the user profile attribute as defined in the user schema (for example, email or address.postalCode). This property is required.
    attributes.required A boolean that specifies whether the user is required to provide a value for the attribute. This property is required.
    preventMultiplePromptsPerFlow A boolean that specifies whether the progressive profiling action will not be executed if another progressive profiling action has already been executed during the flow. This property is required.
    promptIntervalSeconds An integer that specifies how often to prompt the user to provide profile data for the configured attributes for which they do not have values. This property is required.
    promptText A string that specifies text to display to the user when prompting for attribute values. This property is required.
    AGREEMENT action data model
    Property Description
    agreement The relationship to the agreement to which the user must consent. The agreement must exist and be enabled. An agreement cannot be disabed if an action uses it. An enabled agreement must always support the default language. This property is required.
    agreement.id A string that specifies the ID of the agreement to which the user must consent. This property is required.
    IDENTITY_PROVIDER action data model
    Property Description
    acrValues A string that designates the sign-on policies included in the authorization flow request. Options can include the PingOne predefined sign-on policies, Single_Factor and Multi_Factor, or any custom defined sign-on policy names. Sign-on policy names should be listed in order of preference, and they must be assigned to the application. This property can be configured on the identity provider action and is passed to the identity provider if the identity provider is of type SAML or OPENID_CONNECT.
    entraIdEnabled An optional boolean used to specify the policy purpose. Applicable only when identityProvider.id relates to a Microsoft Identity Provider, where the Identity provider’s type property value is set to MICROSOFT.
    identityProvider A reference to the external identity provider that is used to authenticate the user. This property is required.
    identityProvider.id A string that specifies the ID of the external identity provider to which the user is redirected for sign-on. This property is required.
    passUserContext A boolean that specifies whether to pass in a login hint to the identity provider on the authentication request. Based on user context, the login hint is set if (1) the user is set on the flow, and (2) the user already has an account link for the identity provider. If both of these conditions are true, then the user is sent to the identity provider with a login hint equal to their externalId for the identity provider (saved on the account link). If these conditions are not true, then the API checks see if there is an OIDC login hint on the flow. If so, that login hint is used. If none of these conditions are true, the login hint parameter is not included on the authorization request to the identity provider.
    registration Specifies the account registration options.
    registration.confirmIdentityProviderAttributes A boolean that specifies whether users must confirm data returned from an identity provider prior to registration. Users can modify the data and omit non-required attributes. Modified attributes are added to the user's profile during account creation. This is an optional property. If omitted, the default value is set to false.
    registration.enabled A boolean that specifies the enabled/disabled state of the policy action. The property is disabled by default when creating a new policy. When enabled, it allows the use of the new user registration flow. This attribute should be set to true when implementing the social login sign-on policy option.
    registration.population.id A string that specifies the population ID associated with the newly registered user.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    signOnPolicies ACTION.CREATED
    signOnPolicies ACTION.UPDATED
    signOnPolicies ACTION.DELETED
    Response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    204 Successfully removed. No content.
    400 The request could not be completed.
    403 You do not have permissions or are not licensed to make this request, or your license is exceeded.
    404 The requested resource was not found.

    Create Sign-On Policy Action (LOGIN)

    Create Sign-On Policy Action (MFA)

    Create Sign-On Policy Action (IDENTIFIER_FIRST)

    Create Sign-On Policy Action (PROGRESSIVE_PROFILING)

    Create Sign-On Policy Action (AGREEMENT)

    Create Sign-On Policy Action (IDENTITY_PROVIDER)

    Read All Sign-On Policy Actions

    Read One Sign-On Policy Action

    Update Sign-On Policy Action

    Delete Sign-On Policy Action

    Identity Management

    An identity is a unique user resource within PingOne that interacts with the applications and services in the environment to which the user is assigned. The PingOne platform includes numerous services that define and configure a user identity.

    • Users and the user schema

      The users endpoints enable directory operations to create and manage user accounts, including assigning the user to a population, assigning user roles, managing passwords, managing MFA devices, unlocking a user account, managing user consents, and managing ID verification transaction records. It also supports an import capability that gives privileged applications the ability to create a new user and set the user's password.

      For more information, see Users.

      For information about user core attributes and about adding custom attributes to the user schema, see Schemas.

    • Credential Issuance

      The Credentials Issuance API provides endpoints to create custom verifiable credentials for users. The resulting credentials can then be shared with native applications. For more information, see PingOne Credentials.

    • Groups

      The groups API provides endpoints to create collections of users with the same access to applications. For more information, see Groups.

    • Identity provider management

      The identity provider endpoints manage external identity provider configurations. It enables the social login, authoritative login, and inbound SAML login features in PingOne. For more information, see Identity Provider Management.

    • Identity propagation

      The identity propagation API provides for configurable and audit-capable propagation of identities and their attributes between identity stores owned or managed by a customer. For more information, see Identity Propagation (Provisioning).

    Identity Provider Management

    The identity provider (IdP) endpoints manage external IdP configurations. It is one of several related services that enable the social login, authoritative login, and inbound SAML login features in PingOne. An external IdP configuration allows users whose accounts are linked to PingOne to authenticate and gain access to PingOne resources using the login flow and credentials provided by the external IdP.

    PingOne supports several external IdPs. IdP resources in PingOne configure the external IdP settings, which include the type of provider and the user attributes from the external IdP that are mapped to PingOne user attributes. These attributes might have one or many values assigned to them. As you might expect, mapping a single-value IdP attribute to a single-value PingOne attribute results in a PingOne attribute having the same value as the IdP attribute. Similarly, if the IdP attribute is multi-valued, the PingOne attribute value will be an array of the IdP attribute values. If the attributes are not the same format, then the following rules apply:

    • If the IdP attribute is single-valued and the PingOne attribute is multi-valued, the PingOne attribute will be a single-element array containing the value of the IdP attribute.
    • If the IdP attribute is multi-valued and the PingOne attribute is single-value, then the PingOne attribute will use the first element in the IdP attribute as its value.

    The mapping attribute placeholder value must be expressed using the following syntax in the request body:

    ${providerAttributes.<IdP attribute name>}

    Account linking

    PingOne cannot guarantee that usernames are unique for all external IdPs. To prevent users from different IdPs being treated as the same PingOne user, PingOne uses account linking. The user must have a PingOne account. When the user signs in to PingOne, an account link between the external IdP user account and their PingOne account is created.

    Account linking only applies when the user’s authoritative IdP is PingOne. Account linking is not supported when the authoritative IdP is an external IdP rather than PingOne. In this case, account linking will fail. For a user to link their account with multiple external IdPs, their authoritative IdP must be set to PingOne.

    For more information about identity providers, see External IDPs in the PingOne Admin Guide.

    Use cases

    Base IdP data model

    Property Type Required? Mutable? Description
    description String Optional Mutable The description of the IdP.
    enabled String Required Mutable The current enabled state of the IdP. Options are ENABLED or DISABLED.
    environment.id String Required Immutable The environment associated with the IdP resource.
    icon.id String Optional Mutable The ID for the IdP icon.
    icon.href String Optional Mutable The HREF for the IdP icon.
    id String Required Immutable The resource ID.
    loginButtonIcon.id String Optional Mutable The image ID for the IdP login button icon. For Facebook, Google, and LinkedIn IdPs, updates to the login button are ignored to preserve the IdP branding rules.
    loginButtonIcon.href String Optional Mutable The HREF for the IdP login button icon image file. For Facebook, Google, and LinkedIn IdPs, updates to the login button are ignored to preserve the IdP branding rules.
    name String Required Mutable The name of the IdP.
    pkceMethod String Optional Mutable The method for PKCE. Options are NONE or S256. The default is NONE. This value auto-populates from a discovery endpoint if the OpenID Provider includes S256 in its code_challenge_methods_supported claim. The plain method is not currently supported.
    registration.population.id Object Optional Mutable An external IdP to use as authoritative. Setting this attribute gives management of linked users to the IdP and also triggers just-in-time provisioning of new users. These users are created in the population indicated with registration.population.id.
    sloBinding String Optional Mutable The binding protocol to be used for the logout response. Options are HTTP_REDIRECT or HTTP_POST. The default is HTTP_POST; existing configurations with no data default to HTTP_POST. This is an optional property.
    sloEndpoint String Optional Mutable The logout endpoint URL. This is an optional property. However, if a sloEndpoint logout endpoint URL is not defined, logout actions result in an error.
    sloResponseEndpoint String Optional Mutable The endpoint URL to submit the logout response. If a value is not provided, the sloEndpoint property value is used to submit SLO response.
    sloWindow Integer Optional Mutable Defines how long PingOne can exchange logout messages with the application, specifically a LogoutRequest from the application, since the initial request. PingOne can also send a LogoutRequest to the application when a single logout is initiated by the user from other session participants, such as an application or identity provider. This setting is per application. The SLO logout is separate from the user session logout that revokes all tokens.
    spSigning.algorithm String Optional Mutable The signing key algorithm used by PingOne. Value will depend on which key algorithm and signature algorithm you chose when creating your signing key. Possible values are SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withECDSA, SHA384withECDSA, SHA512eithEDCSA.
    spSigning.key.id String Optional Read-only The UUID of the signing key. See Adding a Certificate and Key Pair.
    type String Required Immutable The IdP type. This is a required property. Options are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, and SAML.

    Mapping attributes data model

    Property Type Required? Mutable? Description
    mappingType String Optional Immutable The mapping type. Options are: CORE (This attribute is required by the schema and cannot be removed. The name and update properties cannot be changed.) or CUSTOM (All user-created attributes are of this type.)
    name String Required Mutable The user attribute, which is unique per provider. The attribute must not be defined as read only from the user schema or of type COMPLEX based on the user schema. Valid examples: username, and name.first. The following attributes may not be used: account, id, created, updated, lifecycle, mfaEnabled, and enabled.
    value String Required Mutable A placeholder referring to the attribute (or attributes) from the provider. Placeholders must be valid for the attributes returned by the IdP type and use the ${} syntax (for example, username="${email}"). For SAML, any placeholder is acceptable, and it is mapped against the attributes available in the SAML assertion after authentication. The ${samlAssertion.subject} placeholder is a special reserved placeholder used to refer to the subject name ID in the SAML assertion response.
    update String Required Mutable Indicates whether to update the user attribute in the directory with the non-empty mapped value from the IdP. Options are: EMPTY_ONLY (only update the user attribute if it has an empty value); ALWAYS (always update the user attribute value).

    Attribute type mapping rules

    User attribute type Provider JSON value type Result
    String * Valid. The value is cast at runtime, as necessary.
    Complex * Error
    Boolean Boolean Valid
    Boolean * Error
    JSON Object Valid
    JSON * Error
    JSON (sub-attribute) * Valid

    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.
    500 An unexpected error occurred.

    Identity Providers

    PingOne supports many of the most common external identity providers. While the POST {{apiPath}}/environments/{{envID}}/identityProviders endpoint operation used to create an identity provider resource is the same for each provider, the configuration properties and their values differ. This section shows the configuration properties for each supported external identity provider.

    Create Identity Provider (Facebook)

    Create Identity Provider (Google)

    Create Identity Provider (LinkedIn Legacy Deprecated)

    Create Identity Provider (LinkedIn OIDC)

    Create Identity Provider (Yahoo)

    Create Identity Provider (OpenID Connect)

    Create Identity Provider (Amazon)

    Create Identity Provider (Twitter)

    Create Identity Provider (Apple)

    Create Identity Provider (Paypal)

    Create Identity Provider (Microsoft)

    Create Identity Provider (Github)

    Create Identity Provider (SAML)

    Discover OpenID Provider Metadata

    Read All Identity Providers

    Read One Identity Provider

    Update Identity Provider

    Delete Identity Provider

    Identity Provider Attributes

    When defining an external identity provider resource, user attributes from the external identity provider are mapped to PingOne user attributes. The mapping attribute placeholder value must be expressed using the following syntax in the request body:

    ${providerAttributes.<IdP attribute name>}

    For example, the request body for the Facebook-to-PingOne email-to-email mapping looks like this, with the value attribute showing the Facebook email attribute expressed using the placeholder syntax:

    {
    "name": "email",
    "update": "EMPTY_ONLY",
    "value": "${providerAttributes.email}"
}

    Create Identity Provider Attribute (Facebook)

    Create Identity Provider Attribute (Google)

    Create Identity Provider Attribute (LinkedIn Legacy Deprecated)

    Create Identity Provider Attribute (LinkedIn OIDC)

    Create Identity Provider Attribute (Yahoo)

    Create Identity Provider Attribute (OpenID Connect)

    Create Identity Provider Attribute (Amazon)

    Create Identity Provider Attribute (Twitter)

    Create Identity Provider Attribute (PayPal)

    Create Identity Provider Attribute (Microsoft)

    Create Identity Provider Attribute (Github)

    Create Identity Provider Attribute (Apple)

    Create Identity Provider Attribute (SAML)

    Read All Identity Provider Attributes

    Read One Identity Provider Attribute

    Update Identity Provider Attribute

    Delete Identity Provider Attribute

    Identity Propagation (Provisioning)

    The identity provisioning service provides for configurable and audit-capable propagation of identities and their attributes between identity stores owned or managed by a customer.

    Companies prefer to use one identity provider, a service or on-premise software, as the single source of truth for all corporate identities. If other services or software require their own dedicated identity store, the preference is to propagate identities from the single source of truth to those other dedicated identity stores. This significantly reduces the possibility of introducing inconsistencies in identities and their associated data across all systems.

    The identity provisioning service creates connectors that permit near real-time updates from PingOne Directory to other identity stores and periodic propagation of updates from other identity stores into PingOne Directory. Other dedicated identity stores can also propagate their updates into PingOne Directory through the API requests of the PingOne SCIM service.

    You can build as many connectors as required to achieve your required use cases. For example, an existing Human Resources application is the source store for high-level identities. It propagates its core identity data to PingOne Directory via SCIM, either through an inbound SCIM connector or through the SCIM service's API. PingOne Directory provides additional identity attributes. PingOne Directory propagates appropriate identities, with needed attributes, through outbound connectors to Slack and Zoom so that new users can quickly use those productivity apps!

    An identity propagation configuration consists of:

    • Revisions

      The configuration revision instances of the state of the plan, store, rule, and mapping, entities of a configuration taken at a point in time. For more information, see Propagation revisions.

    • Plans

      A collection of unidirectional provisioning relationships between pairs of identity stores. For more information, see Propagation plans.

    • Stores

      A connection to an identity store owned by a customer. For more information, see Propagation stores.

    • Store metadata

      The configuration properties for the store type. For more information, see Propagation store metadata.

    • Rules

      A unidirectional provisioning relationship between a subset of identities on a source identity store and a target identity store. For more information, see Propagation rules.

    • Mappings

      The attribute mappings associated with identity propagation rules. For more information, see Propagation mappings.

    Identity propagation configuration revision instances are snapshots of the state of the plan, store, rule, and mapping entities of a configuration taken at a point in time. A new configuration revision can be created at any time, capturing the current state of those resources.

    The API supports the configuration of one or more identity propagation plans on behalf of a customer environment. After configuration, the identity propagation plans are executed in response to changes on watched identity stores. Over time, identities become consistent across all watched (source) and unwatched (target) identity stores defined in an identity propagation plan. Identities are created, updated, and deleted as specified by each plan.

    Creating, modifying, or deleting an identity propagation plan can occur at any time with no effect on the contents of the source identity store, which is the PingOne directory. All actions taken by the can be audited after-the-fact. The contents of identity stores can be modified at any time by external parties, such as administrators or other automated systems. The identity propagation system detects and logs any modifications.

    The system monitors the availability of identity stores identified in the plans. If an identity store becomes unavailable, plan execution is paused until the store becomes available again.

    Identities from managed identity stores are never duplicated or stored in full by the identity propagation system or its component services. Change summaries and change orders containing some attributes of identities are stored briefly during the provisioning process and can be present in audit logs.

    Putting it all together

    To better understand how all the components of propagation work together, see the use case Create a Workday propagation connection. This is the most complicated propagation use case because it has additional steps unique to Workday (clearly identified in the use case). Propagation connections with other identity stores use all steps not marked as applicable only to Workday.

    Use cases

    Propagation Revisions

    Identity propagation configuration revision instances are snapshots of the state of the plan, store, rule, and mapping entities of a configuration taken at a point in time. A new configuration revision can be created at any time, capturing the current state of those resources.

    The examples that follow show common actions to find and manage identity propagation and configuration revision resources. You need the Environment Admin role to perform operations on identity propagation and configuration revision resources.

    Identity propagation revision data model
    Property Type Required? Mutable? Description
    createdAt DateTime N/A Read-only Date and time the propagation revision was created
    createdBy String N/A Read-only Unique identifier (UUID) of the actor who created the propagation revision
    environment.id String N/A Read-only Unique identifier (UUID) of the PingOne environment associated with this propagation revision
    id String N/A Read-only Unique identifier (UUID) of the propagation revision
    previousRevision.id String N/A Read-only Unique identifier (UUID) of the previous configuration revision snapshot
    Response codes
    Code Message
    200 Successful operation.
    201 Successfully created.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Create Propagation Revision

    Read Latest Propagation Revision

    Read Previous Propagation Revision

    Propagation Plans

    Identity propagation plan entities represent a collection of unidirectional provisioning relationships between pairs of identity stores. At this time, a customer can define one plan per environment, owning zero or more rules, which in turn may own zero or more mappings. Deleting a plan instance must also delete all associated rule and mapping instances. A plan is recognized by the provisioning engine when it has an active status and it defines at least one rule.

    The examples that follow show common actions to find and manage identity propagation plan resources. You need the Environment Admin role to perform operations on identity propagation plan entities.

    Propagation plan data model

    Property Type Required? Mutable? Description
    environment.id String N/A Read-only Unique identifier (UUID) of the PingOne environment associated with this propagation plan
    id String N/A Read-only Unique identifier (UUID) of the propagation plan
    name String Required Mutable Unique name of the propagation plan
    status String Optional Mutable Status of the propagation plan; defaults to INACTIVE

    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.
    404 The requested resource was not found.

    Create Plan

    Read All Plans

    Read One Plan

    Update Plan

    Delete Plan

    Propagation Stores

    Identity propagation store entities represent a connection to an identity store owned by a customer. Store instances may be associated with multiple rule entities, and must not be deleted when referred to by a rule instance.

    The examples that follow show common actions to find and manage identity propagation store resources. You need the Environment Admin role to perform operations on identity propagation store entities.

    Propagation stores are directional relative to Ping Identity.

    • For Outbound provisioning, a store in Ping Identity is the source and an outside identity store is the target. You must create an identity propagation store of type directory as the source store. Changes to users propagate near real-time - when there is a change to a user in PingOne, the target identity store is updated immediately.

    • For Inbound provisioning, a store in Ping Identity is the target and an outside identity store is the source. You must create an identity propagation store of type PingOne as the target store. Changes to users are retrieved from the source identity store by polling the remote store every 4 hours. The polling interval is not configurable. You can also use inbound SCIM for inbound user provisioning. For more information, see SCIM.

    Every propagation store is either a target store or a source store. When you create the propagation rule, you designate, by its identifier, which identity store is the source store and which identity store is the target store. For information on inbound and outbound capabilities for each connection type, see Inbound and outbound provisioning.

    Propagation store data models:

    Propagation store base data model

    Property Type Required? Mutable? Description
    configuration Object Required Mutable Configuration properties specific to each identity propagation store as described in subsequent tables.
    description String Optional Mutable A description for the identity propagation store.
    environment.id String N/A Read-only Unique identifier (UUID) of the PingOne environment associated with the propagation store.
    id String N/A Read-only Unique identifier (UUID) of the propagation store.
    image.href String Optional Mutable The URL for the identity store resource image file.
    image.id String Optional Mutable The image ID for the identity store resource.
    managed Boolean Optional Mutable Indicates whether or not to enable deprovisioning of users for a store when it is deleted. The deprovisioning occurs when a new revision is created (POST {{apiPath}}/environments/{{envID}}/propagation/revisions).
    name String Required Mutable The name of the identity store.
    populations.id (Deprecated) String[] Optional Mutable Deprecated, use populations.id in Propagation Rules. Array of population resource identifiers associated with this store.
    status String Optional Mutable The status of the identity store. The default value is INACTIVE.
    syncStatus.details String N/A Read-only Details of any synchronization errors.
    syncStatus.failedCount Integer N/A Read-only A count of failed synchronization events since the last revision.
    syncStatus.failedDeprovisionCount Integer N/A Read-only A count of failed deprovisioning synchronization events since the last revision.
    syncStatus.lastSyncAt DateTime N/A Read-only The last synchronization in yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format.
    syncStatus.successCount Integer N/A Read-only A count of successful synchronization events since the last revision.
    syncStatus.syncState String N/A Read-only The current state of synchronization with a propagation store or stores. Options are either SYNCING or FAILED.
    syncStatus.userTotal Integer N/A Read-only A count of users that will synchronize to the target store based on the Rule’s filter.
    syncStatus (Deprecated) Object N/A Read-only Deprecated, use syncStatus in Propagation Rules. The current state of synchronization with a propagation store or stores.
    type String Required Immutable The type of the identity store and determines the required and acceptable configuration properties. It also determines the acceptable target attribute mappings. Options are Aquera, AzureActiveDirectorySAML2, directory, LdapGateway, PingOne, Salesforce, SalesforceContacts, scim, Slack, Workday, or Zoom.

    Propagation store Aquera configuration data model

    Property Type Required? Mutable? Description
    configuration.ACCESS_TOKEN String Optional Mutable A string specifying the access token for account authentication.
    configuration.AUTHENTICATION_METHOD String Required Mutable The account authentication method. For example, OAuth Bearer Token or Basic Auth.
    configuration.BASIC_AUTH_PASSWORD String Required Mutable The password for account authentication.
    configuration.BASIC_AUTH_USER String Required Mutable The user name for account authentication.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.createNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.disableNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DISABLE_USERS. Whether or not users are allowed to be disabled.
    configuration.GROUP_NAME_SOURCE String Optional Mutable The source to use for the group name. Options are either Common Name or Distinguished Name.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Options are either Disable or Delete.
    configuration.SCIM_URL String Required Mutable The SCIM URL.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.
    configuration.updateNewUsers (Deprecated) Boolean Optional Mutable Deprecated, useconfiguration.UPDATE_USERS. Whether or not users are allowed to be updated.

    Propagation store Azure Active Directory SAML V2.0 configuration data model

    Property Type Required? Mutable? Description
    configuration.ClientId String Required Mutable The Azure Active Directory client ID.
    configuration.ClientSecret String Required Mutable The Azure Active Directory client secret.
    configuration.CREATE_NEW_USERS (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DEPROVISION_USER_ACTION_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.REMOVE_ACTION. The action to take when deprovisioning (removing) a user. Can be Disable or Delete.
    configuration.DEPROVISION_USERS Boolean Optional Mutable Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.PROVISION_DISABLED_USERS_PROV_OPT Boolean Optional Mutable Whether or not disabled users can be provisioned. Defaults to true and, if used, must be set to true.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Can be Disable or Delete.
    configuration.REMOVE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DISABLE_USERS. Whether or not users are allowed to be disabled.
    configuration.RemoveLicensesWhenSkuIdEmpty Boolean Required Mutable Whether or not remove licenses from user when skuId is empty.
    configuration.TenantDomain String Required Mutable The account's Azure Active Directory domain.
    configuration.UPDATE_NEW_USERS (Deprecated) Boolean Optional Mutable Deprecated, useconfiguration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store directory configuration data model

    An identity propagation store of type directory has no configuration data model.

    Propagation store GitHubEMU configuration data model

    Property Type Required? Mutable? Description
    configuration.BASE_URL String Required Mutable Base URL of the target propagation store.
    configuration.CREATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DEPROVISION_USERS Boolean Optional Mutable Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.OAUTH_ACCESS_TOKEN String Required Mutable OAuth 2 access token.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Can be Disable or Delete.
    configuration.REMOVE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DEPROVISION_USERS. Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.UPDATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store GoogleApps configuration data model

    Property Type Required? Mutable? Description
    configuration.APPLICATION_NAME String Required Mutable Name of the application using the store.
    configuration.CREATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DEPROVISION_USERS Boolean Optional Mutable Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.DOMAIN String Required Mutable The account's domain name.
    configuration.OAUTH_ACCESS_TOKEN String Required Mutable OAuth 2 access token.
    configuration.OAUTH_CLIENT_ID String Required Mutable GoogleApps identifier of the client associated with the propagation store.
    configuration.OAUTH_CLIENT_SECRET String Required Mutable GoogleApps secret of the client associated with the propagation store.
    configuration.OAUTH_REFRESH_TOKEN String Required Mutable OAuth 2 refresh token.
    configuration.PROVISION_DISABLED_USERS_PROV_OPT Boolean Optional Mutable Whether or not disabled users can be provisioned. Defaults to true and, if used, must be set to true.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Can be Disable or Delete.
    configuration.REMOVE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DEPROVISION_USERS. Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.UPDATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store LDAP Gateway configuration data model

    Property Type Required? Mutable? Description
    configuration.ATTRIBUTE_METADATA String Optional Mutable User-defined attribute metadata.
    configuration.CLIENT_ID String Required Mutable Identifier of the client for authentication.
    configuration.CLIENT_SECRET String Required Mutable Secret of the client for authentication.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DELETE_USERS Boolean Optional Mutable Whether or not users are allowed to be deleted.
    configuration.ENVIRONMENT_ID String Required Immutable Identifier, a UUID, of the environment the connector services.
    configuration.GATEWAY_BASE_URL String Required Mutable Base URL of the gateway.
    configuration.GATEWAY_ID String Required Mutable Identifier of the gateway to which the connector connects.
    configuration.LDAP_TYPE String Required Immutable Type of LDAP gateway; can be PingDirectory or Microsoft Active Directory.
    configuration.OAUTH_URL String Required Mutable URL to which OAUTH requests are sent.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store PingOne configuration data model

    Property Type Required? Mutable? Description
    configuration.CLIENT_ID String Optional Mutable Unique identifier (UUID) of the PingOne client associated with the propagation store.
    configuration.CLIENT_SECRET String Optional Mutable The PingOne client secret.
    configuration.CREATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DEFAULT_AUTH_METHOD String Optional Mutable The default authentication method. Options are Email 1, SMS 1, or Voice 1.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.ENVIRONMENT_ID Sring Required Mutable Unique identifier (UUID) of the PingOne environment associated with the propagation store.
    configuration.MFA_USER_DEVICE_MANAGEMENT String Optional Mutable How to manage MFA user devices when synchronizing. Options are either Merge with devices in PingOne or Overwrite devices in PingOne.
    configuration.PROVISION_DISABLED_USERS_PROV_OPT Boolean Optional Mutable Whether or not disabled users can be provisioned.
    configuration.REGION String Required Mutable A supported region. Options are "NA", "CA", "EU", or "AP".
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Options are either Disable or Delete.
    configuration.REMOVE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DISABLE_USERS. Whether or not users are allowed to be disabled.
    configuration.UPDATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store Salesforce configuration data model

    Property Type Required? Mutable? Description
    configuration.ACCOUNT_ID String Optional Mutable The Salesforce account ID.
    configuration.CLIENT_ID String Required Mutable The Salesforce client ID.
    configuration.CLIENT_SECRET String Required Mutable The Salesforce client secret.
    configuration.CREATE_NEW_USERS (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.ENABLE_COMMUNITIES Boolean Required Mutable Whether or not to enable Salesforce communities.
    configuration.FREEZE_USER_FLAG Boolean Required Mutable Whether the user account is frozen.
    configuration.OAUTH_ACCESS_TOKEN String Required Mutable OAuth access token for account authentication.
    configuration.OAUTH_REFRESH_TOKEN String Required Mutable OAuth refresh token for account authentication.
    configuration.PERMISSION_SET_MANAGEMENT String Required Mutable The permission sets to be merged with Salesforce.
    configuration.PROFILE_ID String Optional Mutable The Salesforce profile ID.
    configuration.PROVISION_DISABLED_USERS Boolean Optional Mutable Whether or not disabled users can be provisioned.
    configuration.SALESFORCE_DOMAIN String Required Mutable The account's salesforce.com domain.
    configuration.UPDATE_NEW_USERS (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store SalesforceContacts configuration data model

    Property Type Required? Mutable? Description
    configuration.ACCOUNT_ID String Optional Mutable The Salesforce account ID.
    configuration.CLIENT_ID String Required Mutable Unique identifier (UUID) of the Salesforce client associated with the propagation store.
    configuration.CLIENT_SECRET String Required Mutable The Salesforce client secret.
    configuration.CREATE_NEW_USERS (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.ENABLE_COMMUNITIES Boolean Optional Mutable Whether or not to enable Salesforce communities.
    configuration.FREEZE_USER_FLAG Boolean Optional Mutable Whether the user account is frozen.
    configuration.OAUTH_ACCESS_TOKEN String Required Mutable OAuth access token for account authentication.
    configuration.OAUTH_REFRESH_TOKEN String Required Mutable OAuth refresh token for account authentication.
    configuration.PERMISSION_SET_MANAGEMENT String Optional Mutable The permission sets to be merged with Salesforce.
    configuration.PROFILE_ID String Optional Mutable The Salesforce profile ID.
    configuration.PROVISION_DISABLED_USERS Boolean Optional Mutable Whether or not disabled users can be provisioned.
    configuration.RECORD_TYPE String Required Mutable The type of Salesforce record. Options are either Lead or Contact.
    configuration.SALESFORCE_DOMAIN String Required Mutable The account's salesforce.com domain.
    configuration.UPDATE_NEW_USERS (Deprecated) Boolean Optional Mutable Deprecated, useconfiguration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store SCIM configuration data model

    Property Type Required? Mutable? Description
    configuration.AUTHENTICATION_METHOD String Required Mutable The account authentication method. Can be OAuth 2 Client Credentials, OAuth 2 Bearer Token, or Basic Authentication.
    configuration.AUTHORIZATION_TYPE String Required Mutable The authorization header type.
    configuration.BASIC_AUTH_PASSWORD String Required/Optional Mutable The password for account authentication. Required when configuration.AUTHENTICATION_METHOD is Basic Authentication, otherwise optional.
    configuration.BASIC_AUTH_USER String Required/Optional Mutable The user name for account authentication. Required when configuration.AUTHENTICATION_METHOD is Basic Authentication, otherwise optional.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.createNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.disableNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DISABLE_USERS. Whether or not users are allowed to be disabled.
    configuration.GROUP_NAME_SOURCE String Optional Mutable The source to use for the group name. Options are either Common Name or Distinguished Name.
    configuration.GROUPS_RESOURCE String Optional Mutable API endpoint path to the group entity.
    configuration.OAUTH_ACCESS_TOKEN String Required/Optional Mutable OAuth access token for account authentication. Required when configuration.AUTHENTICATION_METHOD is OAuth 2 Bearer Token, otherwise optional.
    configuration.OAUTH_CLIENT_ID String Required/Optional Mutable OAuth client ID. Required when configuration.AUTHENTICATION_METHOD is OAuth 2 Client Credentials, otherwise optional.
    configuration.OAUTH_CLIENT_SECRET String Required/Optional Mutable OAuth client secret. Required when configuration.AUTHENTICATION_METHOD is OAuth 2 Client Credentials, otherwise optional.
    configuration.OAUTH_TOKEN_REQUEST String Required/Optional Mutable OAuth token request endpoint. Required when configuration.AUTHENTICATION_METHOD is OAuth 2 Bearer Token, otherwise optional.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Options are either Disable or Delete.
    configuration.SCIM_URL String Required Mutable The SCIM URL.
    configuration.SCIM_VERSION String Required Mutable The SCIM version.
    configuration.UNIQUE_USER_IDENTIFIER String Required Mutable Specifies the unique user identifier to use. Options are either userName or workEmail.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.
    configuration.updateNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.USER_FILTER String Required Mutable A string that specifies a SCIM filter expression.
    configuration.USERS_RESOURCE String Required Mutable API endpoint path to the user entity.

    Propagation store ServiceNow configuration data model

    Property Type Required? Mutable? Description
    configuration.Administrator_Password String Required Mutable Password for the administrator.
    configuration.Administrator_Username String Required Mutable Username for the administrator.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.createNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.DEPROVISION_USERS Boolean Optional Mutable Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not new users are allowed to be disabled.
    configuration.disableNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DISABLE_USERS. Whether or not users are allowed to be disabled.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Must be set to Disable.
    configuration.ServiceNow_Instance_Name (Deprecated) String Optional Mutable Deprecated, use configuration.ServiceNow_Url. Instance name for the ServiceNow account.
    configuration.ServiceNow_Url String Required Mutable The URL for the ServiceNow account.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.
    configuration.updateNewUsers (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.

    Propagation store Slack configuration data model

    Property Type Required? Mutable? Description
    configuration.CREATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DEPROVISION_USERS Boolean Optional Mutable Whether or not users are allowed to be deprovisioned (removed) following action specified in configuration.REMOVE_ACTION.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled. Must be set to true.
    configuration.OAUTH_ACCESS_TOKEN String Required Mutable OAuth 2 access token.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when deprovisioning (removing) a user. Must be set to Disable.
    configuration.REMOVE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DEPROVISION_USERS. Whether or not users are allowed to be disabled.
    configuration.UNIQUE_USER_IDENTIFIER String Required Mutable The unique user identifier, must be either primaryEmail or userName.
    configuration.UPDATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Propagation store Workday configuration data model

    Property Type Required? Mutable? Description
    configuration.excludeContingentWorkers Boolean Optional Mutable Whether or not contingent workers are excluded.
    configuration.excludeEmployees Boolean Optional Mutable Whether or not employees are excluded.
    configuration.excludeInactiveWorkers Boolean Optional Mutable Whether or not inactive workers are excluded.
    configuration.host String Optional Mutable The Workday API host.
    configuration.password String Required Mutable The password for account authentication.
    configuration.tenantId String Required Mutable The Workday tenant ID.
    configuration.username String Required Mutable The user name for account authentication.

    Propagation store Zoom configuration data model

    Property Type Required? Mutable? Description
    configuration.API_KEY (Deprecated) String Required/Optional Mutable Deprecated, use configuration.OAUTH_* properties with AUTHENTICATION_METHOD of OAuth Bearer Token. The client API key. Required when AUTHENTICATION_METHOD is JWT Bearer Token, otherwise optional.
    configuration.API_SECRET (Deprecated) String Required/Optional Mutable Deprecated, use configuration.OAUTH_* properties with AUTHENTICATION_METHOD of OAuth Bearer Token. The client API secret. Required when AUTHENTICATION_METHOD is JWT Bearer Token, otherwise optional.
    configuration.AUTHENTICATION_METHOD String Optional Mutable Account authentication method. Case sensitive. Can be OAuth Bearer Token or JWT Bearer Token (deprecated). Defaults to OAuth Bearer Token.
    configuration.CREATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.CREATE_USERS. Whether or not users are allowed to be created.
    configuration.CREATE_USERS Boolean Optional Mutable Whether or not users are allowed to be created.
    configuration.DEPROVISION_USERS Boolean Optional Mutable Whether or not users are allowed to be removed (deprovisioned) following the action configured in configuration.REMOVE_ACTION.
    configuration.DISABLE_USERS Boolean Optional Mutable Whether or not users are allowed to be disabled.
    configuration.OAUTH_ACCOUNT_ID String Required/Optional Mutable OAuth account identifier. Required when AUTHENTICATION_METHOD is OAuth Bearer Token, otherwise optional.
    configuration.OAUTH_CLIENT_ID String Required/Optional Mutable OAuth client identifier. Required when AUTHENTICATION_METHOD is OAuth Bearer Token, otherwise optional.
    configuration.OAUTH_CLIENT_SECRET String Required/Optional Mutable OAuth client secret. Required when AUTHENTICATION_METHOD is OAuth Bearer Token, otherwise optional.
    configuration.OAUTH_TOKEN_URL String Required/Optional Mutable OAuth token request endpoint. Required when AUTHENTICATION_METHOD is OAuth Bearer Token, otherwise optional.
    configuration.REMOVE_ACTION String Optional Mutable The action to take when removing (deprovisioning) a user. Options are either Disable or Delete.
    configuration.REMOVE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.DEPROVISION_USERS for disabling users and configuration.DEPROVISION_USERS for deleting users. Whether or not users are allowed to be disabled and deleted.
    configuration.SCIM_URL String Required Mutable The SCIM URL.
    configuration.UPDATE_USERS_PROV_OPT (Deprecated) Boolean Optional Mutable Deprecated, use configuration.UPDATE_USERS. Whether or not users are allowed to be updated.
    configuration.UPDATE_USERS Boolean Optional Mutable Whether or not users are allowed to be updated.

    Error 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.
    404 The requested resource was not found.

    Create Store (Aquera)

    Create Store (AzureActiveDirectorySAML2)

    Create Store (directory)

    Create Store (GitHubEMU)

    Create Store (GoogleApps)

    Create Store (LdapGateway)

    Create Store (PingOne)

    Create Store (Salesforce)

    Create Store (SalesforceContacts)

    Create Store (SCIM)

    Create Store (ServiceNow)

    Create Store (Slack)

    Create Store (Workday)

    Create Store (Zoom)

    Test Connection Configuration

    Read All Stores

    Read One Store

    Read All Synced Stores for a User (deprecated)

    Read One Synced Store for a User (deprecated)

    Update Store

    Delete Store

    Propagation Store Metadata

    Identity propagation store metadata entities represent the configuration properties for the store type. The configuration attribute specifies connection information for a store. The response returns the identity store metadata, specifically the connectionProfiles and the connectionAttributes metadata. The connection profile data provides the information needed to create the identity store configuration connection, and the connection attribute metadata describes available attribute details for target identity store attribute mappings.

    The bodies for the Identity Propagation Store Metadata requests can be the store type configuration or an empty body (that is, {} and not no body at all). If there is any body content, the service attempts to use the configuration to connect to the store provider (provisioner) to get dynamic metadata, if the provisioner supports that. The body can be empty, which returns the basic static metadata, but if the configuration of the store is in the body, some provisioners support getting dynamic attribute metadata when the store provider is queried for user attributes that may include additional attributes. Examples include the maximum configurable metadata for each store type.

    For more information about identity stores, see Propagation stores.

    You need the Environment Admin role to perform operations on identity propagation store metadata entities.

    Propagation Store Metadata Data Model

    Property Type Required? Mutable? Description
    information Object N/A Read-only General information on the connection as described in Properties of information{}
    connectionProfiles Object[] N/A Read-only Array of objects that define different profiles for the connection, such as defining different authentication methods described in Properties of connectionProfiles[]
    attributeMetadata Object N/A Read-only List of all attributes of the connection described in Properties of attributeMetadata{}
    Properties of information{}
    Property Type Required? Mutable? Description
    baseURLRequired Boolean N/A Read-only Whether a base URL is required
    connectionInformationRequired Boolean N/A Read-only Whether connection information is required
    displayName String N/A Read-only Suggested text to show for this connection on a user interface
    identityProvider Boolean N/A Read-only Whether the store is an identity provider
    imageUrl String N/A Read-only URL to an image for the store
    key String N/A Read-only Type of connection; can be Aquera, AzureActiveDirectorySAML2, directory, PingOne, Salesforce, SalesforceContacts, scim, Slack, Workday, or Zoom
    version String N/A Read-only Version of this metadata
    Properties of connectionProfiles[]
    Property Type Required? Mutable? Description
    connectionAttributes.description String N/A Read-only Description of the attribute
    connectionAttributes.displayLabel String N/A Read-only Suggested text to show for this attribute on a user interface
    connectionAttributes.key String N/A Read-only JSON key used to retrieve the attribute value
    connectionAttributes.possibleValues String[] N/A Read-only Array of all permitted values for this attribute
    connectionAttributes.required Boolean N/A Read-only Whether the attribute is required
    connectionAttributes.sensitive Boolean N/A Read-only Whether the attribute is sensitive and requires special handling. Examples of sensitive attributes are passwords and credit card information
    connectionAttributes.typeBoolean Boolean N/A Read-only Whether the attribute is a boolean data type
    description String N/A Read-only Description of the connection
    documentationUrl String N/A Read-only URL to the documentation for the store
    name String N/A Read-only Unique name for the connection
    primary Boolean N/A Read-only Whether this is the primary identity store
    specUrl String N/A Read-only URL to the specification for the store
    Properties of attributeMetadata{}

    The attributeMetadata object contains two objects, userAttributes and groupAttributes, that merit further explanation. Each object contains any number of keys, whose values are objects and named like homeStreetAddress or workPostalCode, that represent a specific attribute of users or groups in the store of the connection. These attribute objects have properties defined in Properties of attributes within userAttributes{} and groupAttributes{} that are common to userAttributes and groupAttributes.

    Property Type Required? Mutable? Description
    capabilities.maxResources Integer N/A Read-only Maximum permitted quantity of this capability
    capabilities.type String N/A Read-only Represents the capability
    enhancements String[] N/A Read-only Array of enhancements (specific behaviors that the provisioner supports), specifically: treat membership as an attribute of a user (MEMBERSHIP_AS_USER_ATTRIBUTE); treat membership as an attribute on a group (MEMBERSHIP_AS_GROUP_ATTRIBUTE); has a get changed type that returns changes across multiple resource-sets (CAN_HANDLE_GET_ALL_CHANGED); operators supported by GET_MATCHING_USERS (OP_AND, OP_OR, OP_NOT, OP_EQ, OP_NE, OP_GT, OP_LT, OP_GTE, _LTE, OP_IN)
    userAttributes Object N/A Read-only User attributes, each an object containing the properties of the attribute
    groupAttributes Object N/A Read-only Group attributes, each an object containing the properties of the attribute
    Properties of attributes within userAttributes{} and groupAttributes{}
    Property Type Required? Mutable? Description
    attributeType String N/A Read-only Type of attribute. This can be STRING, DECIMAL, INTEGER, BOOLEAN
    byteLength Integer N/A Read-only Maximum size of the field in bytes for an INTEGER attribute
    caseSensitive Boolean N/A Read-only Whether value is case sensitive for a STRING attribute
    creatable Boolean N/A Read-only Whether the attribute can be created
    defaultValue N/A Read-only Value that is used as the attribute value if no value is provided in the request and defaultedOnCreate is true
    defaultedOnCreate Boolean N/A Read-only Whether the attribute is defaulted, requires either a provided value or defaultValue, when created
    derived Boolean N/A Read-only Whether the attribute is derived from the value of another attribute
    digits Integer N/A Read-only Maximum number of digits permitted for an INTEGER attribute
    displayName String N/A Read-only Suggested text for this attribute to show on a user interfacee
    distinguishingAttribute Boolean N/A Read-only Whether this attribute can be used as a "secondary GET" option. }
    key String N/A Read-only JSON key used to retrieve the user or group attribute value
    maxLength Integer N/A Read-only Maximum number of characters permitted for a STRING attribute
    maxNumberOfValues Integer N/A Read-only If the attribute is a collection of values (multi-valued), maximum number of values permitted
    minLength Integer N/A Read-only Minimum number of characters permitted for a STRING attribute
    minNumberOfValues Integer N/A Read-only If the attribute is a collection of values (multi-valued), minimum number of values permitted
    nillable Boolean N/A Read-only Whether the attribute value can be empty or null-valued
    ordered Boolean N/A Read-only Whether the order of the attribute collection matters
    pattern String N/A Read-only Regular expression pattern which describes the attribute
    picklistValues [] N/A Read-only Array of all permitted values for this attribute
    precision Integer N/A Read-only Maximum quantity of digits that can be stored to the right of the decimal point for a DECIMAL attribute, excludes the decimal point itself
    referenceAttribute String[] N/A Read-only Array of other names by which the attribute may be referenced, such as emailAddress for email
    requiredOnCreate Boolean N/A Read-only Whether the attribute is required when credating the connection
    requiredOnUpdate Boolean N/A Read-only Whether the attribute is required when updating the connection
    scale Integer N/A Read-only Maximum quantity of digits that can be stored to the left of the decimal for a DECIMAL attribute
    sensitive Boolean N/A Read-only Whether the attribute is sensitive and requires special handling, such as passwords and credit card information
    standard String N/A Read-only ISO standard applicable to the attribute
    type String N/A Read-only Data type of the attribute; can be STRING, DECIMAL, INTEGER, BOOLEAN
    unique Boolean N/A Read-only Whether the attribute value must be unique
    updateable Boolean N/A Read-only Whether the attribute can be updated
    Response codes
    Code Message
    201 Successfully created.
    400 The request could not be completed.

    Identity Propagation Store Metadata (Aquera)

    Identity Propagation Store Metadata (AzureActiveDirectorySAML2)

    Identity Propagation Store Metadata (directory)

    Identity Propagation Store Metadata (GitHubEMU)

    Identity Propagation Store Metadata (GoogleApps)

    Identity Propagation Store Metadata (LdapGateway)

    Identity Propagation Store Metadata (PingOne)

    Identity Propagation Store Metadata (Salesforce)

    Identity Propagation Store Metadata (SalesforceContacts)

    Identity Propagation Store Metadata (SCIM)

    Identity Propagation Store Metadata (ServiceNow)

    Identity Propagation Store Metadata (Slack)

    Identity Propagation Store Metadata (Workday)

    Identity Propagation Store Metadata (Zoom)

    Propagation Rules

    Identity propagation rule entities represent a unidirectional provisioning relationship between a subset of identities on a source identity store and a target identity store. Rules contain attribute mappings, which must be added manually. The PingOne API does not include the default attribute mappings defined by each identity store automatically.

    The PingOne Admin Console does display the default attribute mappings. When defining the connection in the Admin Console, if a rule does not have any user-defined mappings, the identity store's default mappings can be used. If at least one attribute mapping is defined in a rule, then all default mappings are ignored.

    The examples that follow show common actions to find and manage identity propagation rule resources. You need the Environment Admin role to perform operations on identity propagation rule entities.

    Propagation rule data model

    Property Type Required? Mutable? Description
    active Boolean Optional Mutable Whether this rule is active; defaults to false.
    createdAt DateTime N/A Read-only Date and time the propagation rule was created.
    configuration Object Required/Optional Mutable An Outbound LDAP configuration data object is required for outbound LDAP Gateway stores (type LdapGateway). An Inbound LDAP configuration data object is required for an inbound LDAP Gateway stores (where users user are provisioned into PingOne). Optional for all other cases and ignored if used.
    deprovision (deprecated) Boolean Optional Mutable Deprecated, use managed in Propagation Stores. Whether to enable deprovisioning of users for a store when it is deleted. The deprovisioning occurs when a new revision is created (Create Propagation Revision). Not applicable on writeback rules and ignored if used.
    description String Optional Mutable Description of the propagation rule.
    environment.id String N/A Read-only Identifier (UUID) of the PingOne environment associated with the propagation rule.
    groups Object[] Optional Mutable Array of objects, each of which contains the identifier of a group.
    groups.id String Required Mutable Identifier (UUID) of the group to include in this propagation rule.
    id String N/A Read-only Identifier (UUID) of the propagation rule.
    name String Required Mutable Unique name of the propagation rule.
    parentRule.id String Required/Optional Immutable Identifier (UUID) of the inbound propagation rule associated with this writeback propagation rule. Required for a writeback propagation rule, but should not be used with any other propagation rule.
    plan.id String Required Immutable Identifier (UUID) of the propagation plan associated with this propagation rule.
    populationExpression String Optional Mutable SCIM filter on any user attribute of the source identity store to filter the source population. Not applicable on writeback rules and ignored if used.
    populations.id (deprecated) String[] Optional Mutable Deprecated, use populationExpression. If both are present, populationExpression applies and populations.id ignored. Array of identifiers (UUID) of populations associated with this propagation rule. Not applicable on writeback rules and ignored if used.
    sourceStore.id String Required Immutable Identifier (UUID) of the source identity store associated with this propagation rule.
    sourceStore.name String Required Immutable Name of the source identity store associated with this propagation rule.
    syncStatus.failedCount Integer N/A Read-only Count of failed synchronization events since the last revision.
    syncStatus.failedDeprovisionCount Integer N/A Read-only Count of failed deprovisioning synchronization events since the last revision.
    syncStatus.groupFailedCount Integer N/A Read-only Count of failed group synchronization events since the last revision.
    syncStatus.groupSuccessCount Integer N/A Read-only Count of successful group synchronization events since the last revision.
    syncStatus.groupTotal Integer N/A Read-only Count of groups that will synchronize to the target store.
    syncStatus.partialSyncTotal Integer N/A Read-only Count of users for which an account exists at the target but is out of sync with the source because onUpdate is set to false.
    syncStatus.sourceDetails String N/A Read-only Details of any source synchronization errors.
    syncStatus.sourceLastSyncAt DateTime N/A Read-only Last source synchronization in yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format.
    syncStatus.sourceSyncState String N/A Read-only Current state of synchronization with a source store. Can be FAILED, POLLING, or POLL_COMPLETE.
    syncStatus.successCount Integer N/A Read-only Count of successful synchronization events since the last revision.
    syncStatus.targetDetails String N/A Read-only Details of any target synchronization errors.
    syncStatus.targetLastSyncAt DateTime N/A Read-only Last target synchronization in yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format.
    syncStatus.targetSyncState String N/A Read-only Current state of synchronization with a target store. Can be SYNCING, SYNC_COMPLETE, or FAILED.
    syncStatus.unsyncTotal Integer N/A Read-only Count of users for which an account exists at the target but was not synced with the source because onCreate is set to false.
    syncStatus.userTotal Integer N/A Read-only Count of users that will synchronize to the target store based on the propagation rule's filter.
    targetStore.id String Required Immutable Identifier (UUID) of the target identity store associated with this propagation rule.
    targetStore.name String Required Immutable Name of the target identity store associated with this propagation rule.
    updatedAt DateTime N/A Read-only Date and time the propagation rule was updated. Can be null.

    Synchronization states are:

    • FAILED - An error occurred polling users from the source or pushing users to the target.
    • POLL_COMPLETE - Polling has completed on the source.
    • POLLING - Store is polling for users' information from the source to be potentially synchronized.
    • SYNC_COMPLETE - Synchronization has completed on the target.
    • SYNCING - Synchronizing users to the target is successful.
    Outbound LDAP configuration data object

    This outbound LDAP configuration object is required for outbound LDAP Gateway stores (type LdapGateway). An Inbound LDAP configuration data object is required for inbound LDAP Gateway stores (where users user are provisioned into PingOne). For all other cases, optional and ignored if used.

    Property Type Required? Mutable? Description
    BASE_DN String Required Mutable The location in the LDAP directory structure where users will be created.
    RDN_ATTRIBUTE String Required Mutable Relative distinguished name is the portion of the DN (distinguished name) that uniquely identifies the user in the LDAP directory. Must be cn for Microsoft Active Directory, uid for PingDirectory.
    Inbound LDAP configuration data object

    This inbound LDAP configuration object is required for inbound LDAP Gateway stores (where users are provisioned into PingOne). An Outbound LDAP configuration data object is required for outbound LDAP Gateway stores (type LdapGateway). For all other cases, optional and ignored if used.

    If AUTHENTICATE_VIA_AD_LDAP is false, then the GATEWAY_USER_TYPE_* configuration attributes are optional and ignored if used. Note that USERS_BASE_DN is always required and unaffected by the value of AUTHENTICATE_VIA_AD_LDAP.

    AUTHENTICATE_VIA_AD_LDAP can only be true if a userTypes object is configured in the gateway as returned by Read One Gateway. The remaining configuration attributes are required and must exactly match the corresponding attribute in the userTypes array object.

    For example, the object in the userTypes array is:

    "userTypes": [
    {
        "id": "522eea26-d268-4494-a826-434a6b24f35d",
        "name": "AD user type",
        "passwordAuthority": "LDAP",
        "searchBaseDn": "OU=inbound,OU=test,OU=LdapGatewayTest,DC=ldap-test1,DC=lab",
        "orderedCorrelationAttributes": [
            "dn"
        ],
        "allowPasswordChanges": false
    }
],

    The mapping is:

    • allowPasswordChanges maps to GATEWAY_USER_TYPE_ALLOW_PASSWORD_CHANGES
    • id maps to GATEWAY_USER_TYPE_ID
    • name maps to GATEWAY_USER_TYPE_NAME
    • orderedCorrelationAttributes maps to GATEWAY_USER_TYPE_CORRELATION_ATTRIBUTES where, for multiple attributes, the JSON array of strings is converted to a single comma-separated string.
    • passwordAuthority maps to GATEWAY_USER_TYPE_PASSWORD_AUTHORITY
    Property Type Required? Mutable? Description
    AUTHENTICATE_VIA_AD_LDAP Boolean Required Mutable Whether users are authenticated using LDAP.
    GATEWAY_USER_TYPE_ALLOW_PASSWORD_CHANGES Boolean Required/Optional Mutable Whether users are permitted to change their password. Required as described in this section, optional for all other rules and ignored if used.
    GATEWAY_USER_TYPE_CORRELATION_ATTRIBUTES String Required/Optional Mutable A comma-separated string of one or more attributes. Required as described in this section, optional for all other rules and ignored if used.
    GATEWAY_USER_TYPE_ID String Required/Optional Mutable Identifier (UUID) of the user type to which this configuration applies. Required as described in this section, optional for all other rules and ignored if used.
    GATEWAY_USER_TYPE_NAME String Required/Optional Mutable Name of the user type to which this configuration applies. Required as described in this section, optional for all other rules and ignored if used.
    GATEWAY_USER_TYPE_PASSWORD_AUTHORITY String Required/Optional Mutable Password authority associated with the user type. Required as described in this section, optional for all other rules and ignored if used.
    MFA_USER_DEVICE_MANAGEMENT String Optional Mutable How incoming user devices are managed. Can be Merge with devices in PingOne, Overwrite devices in PingOne, or Do not manage devices. For more information, see Provisioning options reference.
    USERS_BASE_DN String Required Mutable The LDAP directory location from where the users will be synced into PingOne.

    Propagation synchronized rule data model

    Property Type Required? Mutable? Description
    details String N/A Read-only Details of any rule synchronization errors.
    environment.id String N/A Read-only Identifier (UUID) of the PingOne environment associated with the propagation rule.
    lastSyncAt DateTime N/A Read-only Last rule synchronization in yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format.
    rule.active Boolean N/A Read-only Whether the rule is active or not.
    rule.id String N/A Read-only Identifier (UUID) of the synchronized rule.
    rule.name String N/A Read-only Name of the synchronized rule.
    sourceStore.id String N/A Read-only Identifier (UUID) of the source identity store associated with this propagation rule.
    sourceStore.name String N/A Read-only Name of the source identity store associated with this propagation rule.
    sourceStore.type String N/A Read-only Type of the source identity store associated with this propagation rule.
    status String N/A Read-only Status of the rule synchronization. Can be SUCCESS or FAILED.
    syncedMemberships Object[] N/A Read-only Array of objects describing the group memberships of the rule and its status within the group.
    syncedMemberships.details String N/A Read-only Details of any rule group synchronization errors.
    syncedMemberships.group.id String N/A Read-only Identifier (UUID) of the group of which the rule is a member.
    syncedMemberships.lastSyncAt DateTime N/A Read-only Last rule group synchronization in yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format.
    syncedMemberships.status String N/A Read-only Status of the rule group synchronization. Can be SUCCESS or FAILED.
    targetStore.id String N/A Read-only Identifier (UUID) of the target identity store associated with this propagation rule.
    targetStore.name String N/A Read-only Name of the target identity store associated with this propagation rule.
    targetStore.type String N/A Read-only Type of the target identity store associated with this propagation rule.
    type String N/A Read-only Status of the rule synchronization. Can be INBOUND or OUTBOUND.

    Additional rule data models by request

    Read All Rules and Read One Plan's Rules return a Propagation rule data model modified as described in the table.

    Property Type Required? Mutable? Description
    rules Object[] N/A Read-only Array of rule objects as defined in Propagation rule data model
    rules.rule Object N/A Read-only Rule object, replaces id in Propagation rule data model
    rules.rule.id String N/A Read-only Unique identifier (UUID) of the propagation rule
    rules.rule.name String N/A Read-only Name of the propagation rule

    The requests Read All Synced Rules for a User, Read One Synced Rule for a User, Read All Synced Rules for a Group, and Read One Synced Rule for a Group return a Propagation rule data model modified as described in the table.

    Property Type Required? Mutable? Description
    syncedRules Object[] N/A Read-only Array of synchronized rule objects as defined in [Propagation rule data model]#propagation-rule-data-model)
    syncedRules.rule Object N/A Read-only Rule object, replaces id in Propagation rule data model
    syncedRules.rule.active Boolean N/A Read-only Whether the rule is active or not
    syncedRules.rule.id String N/A Read-only Unique identifier (UUID) of the propagation rule
    syncedRules.rule.name String N/A Read-only Name of the propagation rule

    The requests Read All Synced Groups for a Rule and Read One Synced Group for a Rule return a Groups data model modified as described in the table.

    Property Type Required? Mutable? Description
    syncedGroups Object[] N/A Read-only Array of synchronized group objects as defined in Groups data model
    syncedGroups.group Object N/A Read-only Group object, replaces id in Groups data model
    syncedGroups.group.id String N/A Read-only Unique identifier (UUID) of the group

    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.
    404 The requested resource was not found.

    Create Rule

    Create Rule (Writeback)

    Read All Rules

    Read One Rule

    Read One Plan's Rules

    Read All Synced Rules for a User

    Read One Synced Rule for a User

    Read All Synced Rules for a Group

    Read One Synced Rule for a Group

    Read All Synced Groups for a Rule

    Read One Synced Group for a Rule

    Update Rule

    Delete Rule

    Propagation Mappings

    Identity propagation mapping entities represent the attribute mappings associated with identity propagation rules. A mapping entity identified an attribute in the source identity store that is mapped to an attribute in the target identity store.

    The examples that follow show common actions to find and manage identity propagation mapping resources. You need the Environment Admin role to perform operations on identity propagation mapping entities.

    Propagation mapping data model

    Property Type Required? Mutable? Description
    environment.id String N/A Read-only Identifier (UUID) of the PingOne environment for the propagation mapping
    expression String Required/Optional Mutable PingOne Expression Language (PEL) expression to create the target attribute, such as supply a literal value, reformat the source value, or combine source user attributes. Either expression or sourceAttribute is required but not both. For more information on PEL, see PingOne expression language
    id String N/A Read-only Identifier (UUID) of the propagation mapping
    name String Required Mutable Unique name of the propagation mapping
    rule.id String Required Immutable Identifier (UUID) of the rule to which this mapping applies
    sourceAttribute String Required/Optional Mutable Source attribute for the mapping. Either expression or sourceAttribute is required but not both.
    targetAttribute String Required Mutable Target attribute for the mapping

    Response codes

    Code Message
    200 Successful operation.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Create Rule Mapping

    Read One Mapping

    Read One Rule Mapping

    Update Mapping

    Delete Mapping

    SCIM

    The System for Cross-domain Identity Management (SCIM) defines an open standard protocol for identity management via HTTP in RFC 7644. The PingOne SCIM API provides support for this protocol within the PingOne platform.

    This PingOne SCIM API makes PingOne a SCIM Service Provider - the system which accepts incoming user provisioning and user update requests. Being a SCIM Client - sending identities outbound for creation in foreign systems - is separate and handled by Identity Propagation (Provisioning) via the SCIM provisioning connector.

    The PingOne SCIM API, at a high level, acts as a translation layer that receives SCIM requests to then issue as equivalent PingOne API requests, and translates PingOne API responses to SCIM-compliant responses for the user.

    PingOne supports only version 2.0 of the SCIM standard. PingOne will not support the 1.1 version of the standard, and the 1.0 version is officially deprecated.

    In the SCIM API sample requests shown in this document, the {{scimPath}} variable in the sample requests represents the regional domain for the PingOne server. See PingOne API domains for more information.

    Highlights of the PingOne SCIM API

    • SCIM is an open standard used for identity management that PingOne supports.
    • Support for SCIM in PingOne is provided by an API that translates HTTP calls between the SCIM client and PingOne.
    • The URI for interacting with the PingOne SCIM API takes the form of: https://scim-api.pingone.com/environments/{{envID}}/v2/.
    • The PingOne SCIM API supports an extended version of SCIM users (that is, users with a URN of urn:ietf:params:scim:schemas:core:2.0:User) as well as “direct-mapped” users.
    • Direct-mapped users allow clients to use the PingOne SCIM API without worrying about schema resource mappings.
    • SCIM users in PingOne include a SCIM extension schema to include PingOne-specific data, such as the population identifier.
    • All user data created via the PingOne SCIM API or directly via the PingOne API can be modified or deleted by using either API, regardless of how the resource was initially created.
    • PingOne does not support some SCIM attributes, such as x509Certificates. Attempts to add or modify this data will be ignored, in accordance with the SCIM protocol.
    • The PingOne SCIM API does not support pagination. Lists of resources, such as ListResponse objects, return no more than 200 elements.
    • Groups are not supported.
    • PingOne supports SCIM POST searches that provide filtering data in a JSON body.
    • PingOne supports querying SCIM resources with attribute filters as query parameters.

    PingOne SCIM API constraints

    Some attributes are multi-valued in the SCIM standard schema, but single-valued in the PingOne schema. These SCIM attributes are emails, phoneNumbers, photos, and addresses. Because PingOne can only accept one value for these attributes, the SCIM API will reject requests that provide more than one values. However, they must still be provided as an array with only one element.

    The SCIM standard states that the HTTP 501 (Not Implemented) error code should be returned when an invalid endpoint is accessed. However, due to infrastructure limitations, invalid endpoints will return an HTTP 404 (Not Found). The exception to this is when established SCIM endpoints that are not supported by PingOne (such as /Me) are queried.

    When the PingOne SCIM API returns a list of results, it returns no more than 200 resources, and it does not page results. In other words, there is no way to see the remainder of the results. This is due to a conflict between the way the RFC describes pagination (with index-based pagination) and the way PingOne implements pagination in the PingOne API (with cursor-based pagination).

    The PingOne SCIM API supports query parameters when retrieving users. However, the service does not support these query parameters defined by the SCIM specification:

    • sortBy
    • sortOrder
    • startIndex

    Atypical behavior

    The PingOne SCIM API provides an additional user resource type called a “direct-mapped user”. This can be used on its own endpoint (/DirectMappedUsers) and provides a mechanism for making SCIM calls without the need for a SCIM resource mapping. See Direct-mapped Users for more information.

    Some of the default SCIM attributes are not necessarily relevant to PingOne, so they are not supported, such as x509Certificates. These attributes have been listed in a later section.

    Telephone numbers provided by clients are not forced to comply with RFC 3966. The service does not force them to be in the format +1-512-123-4567. Instead, telephone numbers are routed to PingOne as submitted.

    SCIM attributes defined in the specification

    According to Section 2.3 of RFC 7643, the type of an attribute may be one of:

    • String
    • Boolean
    • Decimal
    • Integer
    • DateTime
    • Binary
    • Reference
    • Complex

    The PingOne SCIM API’s primary user type on the /v2/Users endpoint is an extension of the one described in the SCIM specification, but is mostly the same. The following Description column describes the relationship between SCIM attributes and its equivalent in the PingOne API, if applicable. It also provides a very brief summary of the purpose of each SCIM attribute. For more details, see sections 3.1 and 4.1.1, and 4.1.2 of RFC 7643.

    Field Type PingOne API equivalent Description
    schemas String None An array of Strings that indicates the SCIM schemas. Duplicate values MUST NOT be included.
    id String id A unique identifier for a SCIM resource. This attribute is always returned by the SCIM API, and is equivalent to the id value in the PingOne API.
    externalId String externalId An optional identifier for the resource, assigned and used by the provisioning client.
    meta Object No equivalent This information is assembled by the PingOne SCIM API itself. All sub-attributes have a mutability of readOnly. This attribute should be ignored when it is provided by clients.
    meta.resourceType String None Indicates the type of the SCIM resource, such as User or Group.
    meta.created DateTime createdAt The timestamp for when the resource was created.
    meta.lastModified DateTime updatedAt The timestamp for when the resource was last updated.
    meta.location String self.href A URI indicating the path to the SCIM resource.
    userName String username The username. This field is required when creating a user.
    name Object name (Complex) A JSON object containing components of a user’s name.
    name.formatted String name.formatted The user's full name.
    name.familyName String name.family The user's family name.
    name.givenName String name.given The user's given name.
    name.middleName String name.middle The user's middle name.
    name.honorificPrefix String name.honorificPrefix A user's title. For example, Mr, Ms, Sir.
    name.honorificSuffix String name.honorificSuffix The user's suffix, such as Jr or III.
    nickName String nickname The nickname of the user. This value should not be used to represent a user’s username.
    title String title The title of the user, such as Vice President or Director.
    preferredLanguage String preferredLanguage Helps PingOne match language tags to a user’s language preferences. This is especially useful when processing interactions that are not directly initiated by the user.
    locale String locale Indicates the user’s default location, which helps localize information such as currency or date-time formats.
    timezone DateTime timezone The user’s time zone. This is set in IANA Time Zone database format.
    active Boolean enabled RFC 7644 declares that "[t]he definitive meaning of this attribute is determined by the service provider." In PingOne, this indicates whether the user is able to authenticate.
    password String password The password of the user. The PingOne SCIM API will never return this attribute under any circumstances or in any form, hashed or otherwise.
    emails Object email (String) The email addresses of the user. The PingOne SCIM API only allows a single value to be provided.
    phoneNumbers Object primaryPhone (String) The phone numbers of the user. The PingOne SCIM API only allows a single value to be provided.
    photos Object photo (Complex) A URI indicating the path to the user’s image. This must be a file (such as .gif, .jpg, .png) and cannot be a web page that contains the image. The PingOne SCIM API only allows a single value to be provided.
    addresses Object address (Complex) A JSON object that contains a set of data pertaining to the user’s address. The PingOne SCIM API only allows a single value to be provided.
    addresses.formatted String None The full mailing address, formatted for display or use with a mailing label. The RFC allows this attribute to contain newlines.
    addresses.streetAddress String address.streetAddress The full street address. This may include house number, street name, Post Office box. The RFC allows this attribute to contain newlines.
    addresses.locality String address.locality The city or locality.
    addresses.region String address.region The state or region.
    addresses.postalCode String address.postalCode The zip code or postal code.
    addresses.country String address.countryCode The name of the country. This MUST be in ISO 3166-1 alpha-2 code format, such as US or SE.

    Additional attributes accepted by the PingOne SCIM API

    This section defines attributes that are not in the SCIM specification, but are allowed (and sometimes required) to be included in SCIM API calls to PingOne. These attributes are defined in the extension schema, urn:pingidentity:schemas:extension:2.0:PingOneUser, allowing clients to provide data custom to PingOne via the /Users endpoint without causing interoperability issues with other SCIM clients.

    Field Type PingOne API equivalent Description
    population Object population A UUID representing the population of a resource. This is required for POST operations only when the environment does not have a default population defined.

    SCIM attributes not supported by PingOne SCIM API

    Some of the default attributes in the SCIM specification do not apply to the PingOne solution. These have been listed below. As per the SCIM specification, modifications involving these attributes will be ignored. This behavior is consistent with how invalid attributes are handled by both SCIM and the PingOne API.

    Field Type Description
    groups Object Support for groups is pending.
    meta.version String The version of the resource. This is essentially the SCIM version of an HTTP ETag, which is not supported in PingOne. Hence, the PingOne SCIM API does not return this attribute.
    displayName String The user’s name in a "displayable" form for an application. This field is not required.
    profileUrl String A URI indicating the path to a user’s online profile. PingOne does not have an equivalent attribute for this purpose.
    userType String Identifies the relationship between the organization and the user, such as Contractor, Employee, Manager.
    ims Object Instant messaging address. PingOne does not have an equivalent attribute for this purpose.
    entitlements Object This attribute represents the user’s ownership or right to certain objects.
    roles Object This attribute generally contains a list of roles for the user that “collectively represent who the user is” (citation: RFC 7643).
    x509Certificates Object Represents a list of certificates that are associated with a resource.

    PingOne SCIM API contracts

    For an example environment with an identifier of fa1afe1, the main structure of the SCIM endpoints in PingOne are URIs in the form: https://scim-api.pingone.com/environments/fa1afe1/v2/Users.

    These are main endpoints used by the PingOne SCIM API:

    • /v2/Users
    • /v2/DirectMappedUsers
    • /v2/ResourceTypes
    • /v2/Schemas
    • /v2/ServiceProviderConfig

    These endpoints are typical for the SCIM standard but are not supported. Sending requests to these endpoints will result in an HTTP 501 (Not Implemented) response.

    • /v2
    • /v2/Bulk
    • /v2/Groups
    • /v2/Me

    SCIM users and populations

    PingOne environments have a construct called populations that allow administrators to separate and maintain different types of users in the same environment. In PingOne, every user is associated with a population. As a result, PingOne must know in which population the user should be placed. To provide this information directly when creating a SCIM user (via /Users endpoint), this can be done by including the data with the extension schema:

    "urn:pingidentity:schemas:extension:2.0:PingOneUser": {
   "population": {
      "id": "5980c790-24c3-4fc6-8144-3d634abdda3a"
   }
}

    A direct-mapped user can specify this information directly, just like the behavior of the PingOne API. Thus, it does not use an extension schema:

    "population": {
   "id": "5980c790-24c3-4fc6-8144-3d634abdda3a"
}

    However, when a default population is defined in the PingOne environment (see default in Populations data model), a population is not required to be explicitly declared. By convention, if any request comes to PingOne that does not explicitly declare the population to use by default, then the user will be created in the default population. Otherwise, a population must be included in the JSON body of the request because PingOne must know with which population the user is associated.

    Lists of SCIM resources

    When multiple SCIM resources are returned in a single response, RFC 7644 states that it must be in the form of a ListResponse object. The RFC also states that pagination should be performed with a page-based implementation, but PingOne only supports cursor-based pagination. The main difference between the two is that page-based pagination requires that the client provide an index parameter, whereas cursor-based pagination provides a next link that can be used to receive the next page of resources.

    From a technical perspective, implementing page-based pagination is not feasible in the PingOne SCIM API when the underlying PingOne architecture uses a cursor-based approach. For this reason, the PingOne SCIM API does not support paging, but instead will return up to 200 results. If more than 200 results are available, the true number of results will be available in totalResults.

    SCIM Users

    A SCIM user reflects the description in RFC 7644 and relies on the SCIM resource mapping defined in the response to Read SCIM2 Schemas. This is in contrast to Direct-mapped Users, where the attribute data of direct-mapped users is given in the same scheme as the PingOne API.

    SCIM user data model

    When this data model is used with the PingOne SCIM API, the PingOne user data model is required to extend this data model with a required attribute.

    Property Type Required? Mutable? Description
    active Boolean Optional Mutable Whether the user is enabled. This attribute is set to true by default when the user is created.
    addresses Object Optional Mutable A JSON object that contains a set of data pertaining to the user’s address. The PingOne SCIM API only allows a single value to be provided.
    addresses.countryCode String Optional Mutable Country name of the address. When specified, the value must be in ISO 3166-1 Alpha-2 code format; such as: US (United States) or SE (Sweden).
    addresses.locality String Optional Mutable City or locality of the address.
    addresses.postalCode String Optional Mutable Zip code or postal code of the address.
    addresses.region String Optional Mutable State or region of the address.
    addresses.streetAddress String Optional Mutable Full street address, which may include house number, street name, P.O. box, and multi-line extended street address information. Can contain newlines.
    created String N/A Read-only Date and time at which the user was created.
    emails String Optional Mutable User's email address.
    externalId String Optional Mutable Identifier (UUID) for the user as defined by the provisioning client. Can be explicitly set to null when updating a user to unset it. Can simplify the correlation of the user in PingOne with the user's account in another system of record. The platform does not use this directly in any way, but it is used by Ping Identity's Data Sync product.
    id String N/A Read-only Identifier (UUID) of the user.
    lastModified String N/A Read-only Date and time the user was last modified. Can be null.
    locale String Optional Mutable User's default location. Can be explicitly set to null when updating a user to unset it. This is used for purposes of localizing such items as currency, date time format, or numerical representations. If provided, a valid value is a language tag as defined in RFC 5646. For example: fr, en-US, es-419, az-Arab, man-Nkoo-GN.
    meta Object N/A Read-only This information is assembled by the PingOne SCIM API itself. All sub-attributes have a mutability of Read-only. This attribute should be ignored when it is provided by clients.
    meta.created DateTime N/A Read-only The timestamp for when the resource was created.
    meta.lastModified DateTime N/A Read-only The timestamp for when the resource was last updated.
    meta.location String N/A Read-only A URI indicating the path to the SCIM resource.
    meta.resourceType String N/A Read-only Type of the SCIM resource, such as User or Group.
    name Object Optional Mutable A JSON object containing components of a user’s name.
    name.familyName String Optional Mutable Family name of the user, or last in most Western languages (for example, 'Jensen' given the full name 'Ms. Barbara J Jensen, III'). Can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    name.formatted String Optional Mutable Fully formatted name of the user (for example 'Ms. Barbara J Jensen, III'). Can be explicitly set to null when updating a name to unset it.
    name.givenName String Optional Mutable Given name of the user, or first name in most Western languages (for example, 'Barbara' given the full name 'Ms. Barbara J Jensen, III'). Can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    name.honorificPrefix String Optional Mutable Honorific prefix of the user (can contain more than one), or title in most Western languages (such as, 'Ms.' given the full name 'Ms. Barbara Jane Jensen, III'). Can be explicitly set to null when updating a name to unset it.
    name.honorificSuffix String Optional Mutable Honorific suffix (can contain more than one) of the user, or suffix in most Western languages (such as, 'III' given the full name 'Ms. Barbara Jane Jensen, III'). Can be explicitly set to null when updating a name to unset it.
    name.middleName String Optional Mutable Middle name (can contain more than one) of the user (such as 'Jane' given the full name 'Ms. Barbara Jane Jensen, III'). Can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    nickname String Optional Mutable User's nickname. Can be explicitly set to null when updating a user to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    password String Optional Mutable The password of the user. The PingOne SCIM API will never return this attribute under any circumstances or in any form, hashed or otherwise.
    phoneNumbers String Optional Mutable The phone numbers of the user. The specification says that this SHOULD be specified in the form of RFC 3966 (for example, +1-201-555-0123), but the PingOne SCIM API accepts telephone numbers as they are provided. Any telephone number is passed to the PingOne API, which decides if the phone number is in an acceptable form. PingOne supports a separate mobilePhone attribute, but the PingOne SCIM API only allows one number, which reflects the value of primaryPhone. See PingOne SCIM API constraints for more details.
    photos.href String Optional Mutable URL that points to a resource location representing the user's image. Can be removed from a user by setting the photo attribute to null. If provided, the resource must be a file (such as a GIF, JPEG, or PNG image file) rather than a web page containing an image and must have a scheme (protocol) of http or https.
    preferredLanguage String Optional Mutable User's preferred written or spoken languages. Can be explicitly set to null when updating a user to unset it. If provided, the format of the value is the same as the HTTP Accept-Language header field (not including 'Accept-Language:') as specified in Section 5.3.5 of RFC 7231.
    timezone String Optional Mutable User's time zone. Can be explicitly set to null when updating a user to unset it. If provided, it must conform with the IANA Time Zone database format RFC 6557, for example: 'America/Los_Angeles'.
    title String Optional Mutable User's title, such as 'Vice President'. Can be explicitly set to null when updating a user to unset it.
    urn:pingidentity:
    schemas:extension:2.0:
    PingOneUser.population.id    		 String Optional Mutable Identifier (UUID) of the population with which the uesr is associated. Optional if the PingOne environment defines a default population, otherwise required.
    username String Required Immutable Username, which must be provided and must be unique within an environment. The username must be a string of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 128 characters.

    PingOne user data model

    When SCIM user data model is used with this service, this data model is required to extend that data model with a required attribute. It is referenced by its URN, urn:pingidentity:schemas:extension:2.0:PingOneUser, from the schema.

    Property Type Required? Mutable? Description
    population.id String Required/Optional Immutable Identifier (UUID) for the population in which the user’s identity exists. Optional if the PingOne environment defines a default population, otherwise required.

    SCIM user search data model

    Property Type Required? Mutable? Description
    filter String Optional Mutable A SCIM query. For information about SCIM syntax and operators, see Filtering collections.
    count Integer Optional Mutable Maximum number of users to return.

    Create SCIM User

    Read All SCIM Users (search)

    Read All SCIM Users

    Read One SCIM User

    Update SCIM User

    Patch SCIM User

    Delete SCIM User

    Direct-mapped Users

    A direct-mapped user is a type of SCIM user that does not rely on a traditional SCIM resource mapping. No central set of definitions explains how to convert SCIM attributes, such as emails (an array), to PingOne attributes, such as email (a single-valued string), or the reverse. Instead, direct-mapped users perform a direct mapping (or “pass-through”) of the attribute data as provided. This is in contrast to SCIM Users, where the attribute data of the user relies on the SCIM resource mapping defined in the response to Read SCIM2 Schemas.

    This endpoint is not part of the SCIM specification. The advantage to direct-mapped users is that it allows clients to use SCIM without worrying about mapping resource definitions between their SCIM data and PingOne. This is especially useful when it comes to data stored in custom attributes.

    In the previous example, instead of constructing a SCIM emails array, a direct-mapped user can be created with a single-valued email attribute by the SCIM client. Direct-mapped users follow the attribute convention of the PingOne API. Because this is a custom PingOne SCIM resource, it is defined under the /ResourceTypes and /Schemas endpoints.

    Direct-mapped user data model

    Property Type Required? Mutable? Description
    account.canAuthenticate Boolean N/A Read-only Whether the user can authenticate at this time.
    account.lockedAt String N/A Read-only Date and time at which the account was locked, if any.
    account.secondsUntilUnlock Integer N/A Read-only Number of seconds remaining until the account will be unlocked.
    account.status String N/A Read-only Status of the account. Can be OK or LOCKED.
    account.unlockAt String N/A Read-only Date and time at which the account will be unlocked.
    accountId String Optional Mutable Identifier (UUID) of the user's account. Can be explicitly set to null when updating a user to unset it. Is organization-specific and has no special meaning within the platform.
    address.countryCode String Optional Mutable Country name of the address. When specified, the value must be in ISO 3166-1 Alpha-2 code format; such as: US (United States) or SE (Sweden).
    address.locality String Optional Mutable City or locality of the address.
    address.postalCode String Optional Mutable Zip code or postal code of the address.
    address.region String Optional Mutable State or region of the address.
    address.streetAddress String Optional Mutable Full street address, which may include house number, street name, P.O. box, and multi-line extended street address information. Can contain newlines.
    createdAt String N/A Read-only Date and time at which the user was created.
    email String Optional Mutable User's email address.
    emailVerified Boolean N/A Read-only Whether the email is verified.
    enabled Boolean N/A Read-only Whether the user is enabled. Set to true by default when the user is created.
    environment.id String N/A Read-only Identifier (UUID) of the environment with which the direct-mapped user is associated.
    externalId String Optional Mutable Identifier (UUID) for the user as defined by the provisioning client. Can be explicitly set to null when updating a user to unset it. Can simplify the correlation of the user in PingOne with the user's account in another system of record. The platform does not use this directly in any way, but it is used by Ping Identity's Data Sync product.
    id String N/A Read-only Identifier (UUID) of the user.
    identityProvider.id String N/A Read-only Identifier (UUID) of the trusted identity provider that is used as the authentication authority for the user. If present, the user must authenticate via this identity provider.
    identityProvider.type String N/A Read-only Type of the trusted identity provider where the user account is managed. If the type is PING_ONE, PingOne is the authentication authority.
    lastSignOn.at String N/A Read-only Date and time of the last successful login of the user.
    lastSignOn.remoteIp String N/A Read-only IP address of the last successful login of the user.
    lifecycle.status String N/A Read-only Lifecycle status for this account. Can be ACCOUNT_OK or VERIFICATION_REQUIRED. This attribute can only be set when importing a user to set the initial account status. If the initial status is set to VERIFICATION_REQUIRED and an email address is provided, a verification email is sent.
    locale String Optional Mutable User's default location. Can be explicitly set to null when updating a user to unset it. This is used for purposes of localizing such items as currency, date time format, or numerical representations. If provided, a valid value is a language tag as defined in RFC 5646. For example: fr, en-US, es-419, az-Arab, man-Nkoo-GN.
    location String N/A Read-only URL that returns thethis user object.
    memberOfGroupIDs String[] N/A Read-only Array of identifiers (UUID) of groups that a user is a member of.
    memberOfGroupNames String[] N/A Read-only Array of names of groups that a user is a member of.
    meta Object N/A Read-only This information is assembled by the PingOne SCIM API itself. All sub-attributes have a mutability of Read-only. This attribute should be ignored when it is provided by clients.
    meta.created String N/A Read-only Date and time the user was created.
    meta.lastModified String N/A Read-only Date and time the user was last modified. Can be null.
    mfaEnabled Boolean N/A Read-only Whether multi-factor authentication is enabled. Set to true by default when the user is created, unless otherwise specified for user.mfaEnabled in MFA Settings.
    mobilePhone String Optional Mutable User's mobile phone number. This might also match primaryPhone. Can be explicitly set to null when updating a user to unset it. If provided, it must consist of at least one digit and must contain no more than 32 characters.
    name.familyName String Optional Mutable Family name of the user, or last in most Western languages (for example, 'Jensen' given the full name 'Ms. Barbara J Jensen, III'). Can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    name.formatted String Optional Mutable Fully formatted name of the user (for example 'Ms. Barbara J Jensen, III'). Can be explicitly set to null when updating a name to unset it.
    name.givenName String Optional Mutable Given name of the user, or first name in most Western languages (for example, 'Barbara' given the full name 'Ms. Barbara J Jensen, III'). Can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    name.honorificPrefix String Optional Mutable Honorific prefix of the user (can contain more than one), or title in most Western languages (such as, 'Ms.' given the full name 'Ms. Barbara Jane Jensen, III'). Can be explicitly set to null when updating a name to unset it.
    name.honorificSuffix String Optional Mutable Honorific suffix (can contain more than one) of the user, or suffix in most Western languages (such as, 'III' given the full name 'Ms. Barbara Jane Jensen, III'). Can be explicitly set to null when updating a name to unset it.
    name.middleName String Optional Mutable Middle name (can contain more than one) of the user (such as 'Jane' given the full name 'Ms. Barbara Jane Jensen, III'). Can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    nickname String Optional Mutable User's nickname. Can be explicitly set to null when updating a user to unset it. Valid characters consists of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 256 characters.
    password String Optional Mutable The password of the user. The PingOne SCIM API will never return this attribute under any circumstances or in any form, hashed or otherwise.
    photo.href String Optional Mutable URL that points to a resource location representing the user's image. Can be removed from a user by setting the photo attribute to null. If provided, the resource must be a file (such as a GIF, JPEG, or PNG image file) rather than a web page containing an image and must have a scheme (protocol) of http or https.
    population.id String Required/Optional Immutable Identifier (UUID) for the population in which the user’s identity exists. Optional if the PingOne environment defines a default population, otherwise required.
    preferredLanguage String Optional Mutable User's preferred written or spoken languages. Can be explicitly set to null when updating a user to unset it. If provided, the format of the value is the same as the HTTP Accept-Language header field (not including 'Accept-Language:') as specified in Section 5.3.5 of RFC 7231.
    primaryPhone String Optional Mutable User's primary phone number. This might also match mobilePhone. Can be explicitly set to null when updating a user to unset it. If provided, it must consist of at least one digit and must not contain more than 32 characters.
    resourceType String Required Immutable Type of the resource. Must be DirectMappedUser for a direct-mapped user.
    schemas String[] N/A Read-only Array of URNs of schemas used.
    timezone String Optional Mutable User's time zone. Can be explicitly set to null when updating a user to unset it. If provided, it must conform with the IANA Time Zone database format RFC 6557, for example: 'America/Los_Angeles'.
    title String Optional Mutable User's title, such as 'Vice President'. Can be explicitly set to null when updating a user to unset it.
    type String Optional Mutable User's type. Can be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the platform. It could have values of Contractor, Employee, Intern, Temp, External, or Unknown.
    updatedAt String N/A Read-only Date and time at which the user was updated.
    username String Required Immutable Username, which must be provided and must be unique within an environment. The username must be a string of any Unicode letter, mark (such as accent, umlaut), math symbol, numeric character, or punctuation. Can contain no more than 128 characters.
    verifyStatus String N/A Read-only Whether ID Validation authentication is enabled. Can be ENABLED, DISABLED, or NOT_INITIATED. Set to NOT_INITIATED by default when the user is created.

    Direct-mapped search data model

    Property Type Required? Mutable? Description
    filter String Optional Mutable A SCIM query. For information about SCIM syntax and operators, see Filtering collections.
    count Integer Optional Mutable Maximum number of users to return.

    Create Direct-mapped User

    Read All Direct-mapped Users (search)

    Read All Direct-mapped Users

    Read One Direct-mapped User

    Update Direct-mapped User

    Patch Direct-mapped User

    Delete Direct-mapped User

    SCIM Operations

    The PingOne SCIM API supports retrieveing information regarding SCIM and the service itself. Specifically, you can retrieve:

    SCIM2 Resource Types data model

    Property Type Required? Mutable? Description
    schemas String[] N/A Read-only Array of schema URNs used by the service for ResourceTypes.
    totalResults Integer N/A Read-only Number of resource types returned.
    Resources Object[] N/A Read-only Array of objects that describe each resource type.
    Resources.schemas String[] N/A Read-only Array of schemas used by the resource type.
    Resources.id String N/A Read-only Unique identifier of the resource type.
    Resources.meta Object N/A Read-only This information is assembled by the PingOne SCIM API itself. All sub-attributes have a mutability of Read-only. This attribute should be ignored when it is provided by clients.
    Resources.meta.resourceType String N/A Read-only The resource type of the resource type, which is always ResourceType for this request.
    Resources.meta.location String N/A Read-only A URI indicating the path to the SCIM resource. This is generated by the PingOne SCIM API itself, and indicates the path to the resource from a SCIM client’s perspective.
    Resources.name String N/A Read-only Name of the resource type.
    Resources.description String N/A Read-only Description of the resource type.
    Resources.endpoint String N/A Read-only The endpoint to reach the resource type. This is what appears in the URL after the scheme (protocol), domain, and /environment/{{environment identifier}}/v2.
    Resources.schema String[] N/A Read-only URN of the schema of the resource type.
    Resources.schemaExtensions Object[] N/A Read-only Any extension schemas used by the resource type.
    Resources.schemaExtensions.schema String N/A Read-only URN of the extension schema.
    Resources.schemaExtensions.required Boolean N/A Read-only Whether the extension schema is required for the resource type.

    Schema data model

    The response to Read SCIM2 Schemas is the definition, in JSON format, of the data models in SCIM Users and Direct-mapped Users.

    Service Provider Configuration data model

    Property Type Required? Mutable? Description
    authenticationSchemes Object[] N/A Read-only Array that specifies supported authentication scheme properties.
    authenticationSchemes.description String N/A Read-only A description of the authentication scheme.
    authenticationSchemes.documentationUri String N/A Read-only An HTTP-addressable URL pointing to the authentication scheme's usage documentation.
    authenticationSchemes.name String N/A Read-only The common authentication scheme name.
    authenticationSchemes.primary Boolean N/A Read-only Whether this scheme is the primary (preferred) authentication scheme.
    authenticationSchemes.specUri String N/A Read-only An HTTP-addressable URL pointing to the authentication scheme's specification.
    authenticationSchemes.type String N/A Read-only The authentication type. Can be oauth, oauth2, oauthbearertoken, httpbasic, or httpdigest.
    bulk.maxOperations Integer N/A Read-only Maximum number of bulk operations permitted in a request.
    bulk.maxPayloadSize Integer N/A Read-only Maximum size of a request body for bulk operations.
    bulk.supported Boolean N/A Read-only Whether bulk operations are supported.
    changePassword.supported Boolean N/A Read-only Whether changing user passwords is supported.
    etag.supported Boolean N/A Read-only Whether HTTP entity-tags are supported in the SCIM meta.version attribute.
    filter.maxResults Integer N/A Read-only Maximum number of results returned by a request.
    filter.supported Boolean N/A Read-only Whether filtering of results is supported.
    meta Object N/A Read-only This information is assembled by the PingOne SCIM API itself. All sub-attributes have a mutability of Read-only. This attribute should be ignored when it is provided by clients.
    meta.created DateTime N/A Read-only Date and time when the resource was created.
    meta.lastModified DateTime N/A Read-only Date and time when the resource was last updated.
    meta.location String N/A Read-only A URI indicating the path to the SCIM resource. This is generated by the PingOne SCIM API itself, and indicates the path to the resource from a SCIM client’s perspective.
    meta.resourceType String N/A Read-only Type of the SCIM resource, which is always ServiceProviderConfig for this request.
    meta.version String N/A Read-only Version of the SCIM resource.
    patch.supported Boolean N/A Read-only Whether SCIM PATCH operations are supported.
    schemas String[] N/A Read-only Array of schemas used by the service for ServiceProviderConfig.
    sort Boolean N/A Read-only Whether sorting of results is supported.

    Read SCIM2 Resource Types

    Read SCIM2 Schemas

    Read Service Provider Configuration

    Groups

    The Groups service enables you to create collections of users having the same access to applications. You can create up to 100,000 groups per environment. There is no limit to the number of users that can belong to a group.

    External groups

    External groups are groups that originate outside of PingOne. An external group is created using a Just In Time (JIT) method by setting the memberOfExternalGroups property when adding a new user. See the Users data model for more information.

    External group constraints

    As opposed to internal PingOne groups, there are a few things external groups cannot do:

    • Cannot set a dynamic filter.
    • Cannot have nested groups
    • Cannot edit group memberships

    Errors will occur if:

    • The total number of internal and external groups exceeds 100,000.
    • The total number of groups for a user exceeds 10,000.

    Groups permissions

    If you have the Identity Data Admin role, you can perform the following operations using the PingOne APIs:

    • Create, read, update, and delete groups
    • Add users to groups
    • Delete users from groups
    • Read group memberships

    If you have the Environment Admin or Client Application Developer role, you can read groups.

    Creating groups

    Use POST {{apiPath}}/environments/{{envID}}/groups to create a new group.

    By default, groups are created per environment. Groups can also optionally be created per population. Do this by specifying a value for population.id in the body of POST {{apiPath}}/environments/{{envID}}/groups. The population.id property is read-only after it is initially set and can be set in POST {{apiPath}}/environments/{{envID}}/groups only.

    Once a group is created, the following conditions apply:

    You cannot move the group:

    • From one population to another
    • From a population to an environment
    • From an environment to a population

    Learn more about creating groups in Creating a group, in the PingOne Admin Guide.

    Adding users to a group

    There are two ways to add users to a group. The first is to directly add them with the POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups operation. These members are included in both the directUserCounts and totalUserCounts properties.

    The second method is to dynamically add users to a group with the userFilter filter property. You can use this filter with the POST {{apiPath}}/environments/{{envID}}/groups and PUT {{apiPath}}/environments/{{envID}}/groups/{{groupID}} operations. Place the filter in the body of the request as shown in the example below:

    {
    ...
    "userFilter": "title eq \'Manager\'",
    ...
}

    When the POST or PUT operations above are executed, all existing users that meet the filter criteria are dynamically added to the group. In addition, all subsequent new users that are added that meet the filter criteria are also added to the group. The filter supports all the operators and properties that are supported when searching user data. See Users for a complete list. Members added in this way are included in the totalUserCounts property, but not the directUserCounts property.

    A population-level group can contain users from that population only, but an environment-level group can contain users from different populations in the same environment.

    Learn more about managing group members in Managing group membership, in the PingOne Admin Guide.

    Removing users from a group

    Members directly added to a group with the POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups operation are removed from the group with the DELETE {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}} operation.

    Members dynamically added to a group with the userFilter filter property are automatically removed from the group when the filter criteria is no longer met. You can do this by changing the filter criteria with PUT {{apiPath}}/environments/{{envID}}/groups/{{groupID}} or by changing the user data to no longer match the filter criteria. You cannot remove these members with the DELETE {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}} operation.

    Nesting groups

    You can nest one group inside another. The members of the nested group dynamically become members of the parent group. Do this by specifying the ID of a group within the body of a POST {{apiPath}}/environments/{{envID}}/groups/{{groupID}}/memberOfGroups operation. Nesting a group essentially creates a child-parent relationship where members of the "child" group inherit the same properties and permissions as the "parent" group.

    For example, assume an environment has three groups: Group A, Group B, and Group C. Each group has access to a single application: Group A has access to App1, Group B has access to App2, and Group C has access to App3.

    • If you nest Group B inside of Group A, then users in Group B will now have access to App1 and App2, and Group A will still only have access to App1.

    • If you nest Group C into Group B, then Group C members will inherit access to App1 (via the nested relationship of Group B to Group A), inherit access to App2 (via the nested relationship of Group C to Group B), and will retain access to App3.

    Group A - App1
    Group B - App1 & App2
        Group C - App1, App2, App3

    Learn more about nested groups in Nested groups, in the PingOne Admin Guide.

    Creating circular references

    You can nest parent groups inside their child groups. Continuing the example from the last section, let us assume you have another group, Group D. Group D has access to App4.

    • If you nest Group D in Group B, Group D inherits access to Group A and Group B apps.

    • If you nest Group B in Group D, creating a circular reference, then both Group B and Group C inherit access to App4.

    Group A - App1
    Group B - App1 & App2, App4
        Group C - App1, App2, App3, App4
        Group D - App1, App2, App4
            Group B - App1, App2, App4

    Removing nested relationship

    Use the DELETE {{apiPath}}/environments/{{envID}}/groups/{{groupID}}/memberOfGroups/{{nestedGroupID}} operation to remove the nested relationship between two groups. Members directly assigned to each group remain unchanged.

    Searching for group membership

    Documentation for the following group membership searches can be found under Users/Group Membership:

    Learn more about searching for groups in Searching for groups, in the PingOne Admin Guide.

    Filtering groups searches

    You can filter groups GET collection responses by applying a SCIM filtering expression to the request URL. For large collections, a filter expression appended to the query returns a targeted, more useful data set.

    The SCIM operators eq (equals), sw (starts with), and, and or can be used with the following group properties:

    • name
    • externalId

    The SCIM operators eq (equals), and sw (starts with) can be used with the group property:

    • displayName

    The SCIM operator eq (equals) can be used with the following group properties:

    • id
    • population.id
    • sourceId (only for external groups)

    For more information see Paging, ordering, and filtering collections.

    You can also use SCIM filters with GET collection requests that return user data. See Users for the user properties and operators supported.

    Use Cases

    Groups data model

    Property Type Required? Mutable? Description
    customData JSON blob Optional Mutable User-defined custom data.
    description String Optional Mutable The group description.
    displayName String Optional Mutable For Just In Time (JIT) creation of external groups, it's set when a user is created or updated with memberOfExternalGroups[].name. See the Users data model for more information. For internal groups it is identical to name. Groups can be filtered by displayName.
    directMemberCounts Object Optional Immutable An object containing a users (int) property. This property lists the number of users explicitly added to the group with POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups. Since these members were explicitly added to the group, they can be removed from the group with DELETE {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}}.
    environment.id String Required Immutable The unique identifier for the environment.
    externalId String Optional Mutable A user-defined identifier for the group. Use this property to synchronize a group in PingOne with the same group in an external system. PingOne does not directly use this property. Search all groups for a specific external ID with a SCIM filter using GET {{apiPath}}/environments/{{envID}}/groups.
    id String Required Immutable The unique identifier for the group. Search all groups for a specific group ID with a SCIM filter on GET {{apiPath}}/environments/{{envID}}/groups. Retrieve all the group IDs associated with a user with GET {{apiPath}}/environments/{{envID}}/users/{{userID}}?include=memberOfGroupIDs.
    isAdmin Boolean N/A Read-only true indicates that admin role assignments are present for this group.
    name String Required Immutable The group name. A group name can be reused across populations, but the same user cannot belong to multiple groups with the same group name. Population groups cannot share a group name with an environment group. Search all groups for a specific group name with a SCIM filter on GET {{apiPath}}/environments/{{envID}}/groups. Retrieve all the group names associated with a user with GET {{apiPath}}/environments/{{envID}}/users/{{userID}}?include=memberOfGroupNames. Use this operation to determine group membership in attribute mappings for claims and assertions.
    population.id String Optional Immutable The unique identifier for the population. Set this property during group creation only. If set, membership to the group is restricted to a single population. For more information, see Creating groups. Search all groups for a specific population ID with a SCIM filter on GET {{apiPath}}/environments/{{envID}}/groups.
    sourceId String Optional Immutable For Just In Time (JIT) creation of external groups, it's set when a user is created or updated with memberOfExternalGroups[].sourceId. See the Users data model for more information. Groups that are provisioned set this property when the groups are created. Groups can be filtered by sourceId.
    sourceType String Optional Immutable For Just In Time (JIT) creation of external groups, it's set when a user is created or updated with memberOfExternalGroups[].sourceType. Currently, this can be only "GATEWAY" or "IDP". See the Users data model for more information.
    totalMemberCounts Object Optional Immutable An object containing a users (int) property. This property lists the total number of users added to the group. You must use GET {{apiPath}}/environments/{{envID}}/groups/{{groupID}} with the include=totalMemberCounts query parameter to retrieve this property. This property is not returned with a list of groups.
    type String Optional Immutable Defines the relationship of nested group membership: DIRECT or INDIRECT.
    userFilter String Optional Mutable A SCIM filter that determines which users are dynamically added to the group. Can only be used to add members of non-admin groups. For more information, see Adding users to a group and Removing users from a group.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    groups GROUP.CREATED
    groups GROUP.UPDATED
    groups GROUP.DELETED
    groups MEMBER_OF_GROUP.CREATED
    groups MEMBER_OF_GROUP.DELETED
    groups GROUP.NESTING_UPDATE
    user MEMBER_OF_GROUP.CREATED
    user MEMBER_OF_GROUP.DELETED

    Groups 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.
    404 The requested resource was not found.

    Create Group

    Create Group Nesting

    Read All Groups

    Read One Group

    Read Group Nesting

    Update Group

    Delete Group

    Delete Group Nesting

    Group Role Assignments

    The Group Role Assignment service allows you to assign administrative roles to a group of users, rather than having to assign roles to each user individually.

    For more information about user groups, see Groups.

    For more information about administrative roles, see Roles.

    Role assignment scopes can be:

    • Organization

    • Environment

    • Population

    • Application

    Group Role Assignment data model

    Property Type Required? Mutable? Description
    environment.id String N/A Read-only The UUID of the environment to which this group belongs.
    group.id String Required Mutable The UUID of the user group.
    readOnly Boolean Required Mutable Whether the admin roles have write permissions appropriate to their roles.
    role.id String Required Immutable The UUID of the role assigned to a group.
    scope.id String Required Immutable The role assignment scope ID. When this is an application ID, because an application ID is guarenteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.
    scope.type String Required Mutable The type of resource defining the scope of the Role assignment. Options are ORGANIZATION, ENVIRONMENT, and POPULATION, APPLICATION.

    Create Group Role Assignment

    Read All Group Role Assignments

    Read One Group Role Assignment

    Delete Group Role Assignment

    Password Policies

    Password policies are scoped to the environment, enabling you to set default password policies for all users in the environment. The password policies are applied to users through populations in the environment. You can assign a password policy to a population using either Update Population or Create Population. You cannot delete a password policy if it is set as the default for the environment, or is referenced by a population.

    Each environment is initialized with 3 password policies: “Standard”, “Passphrase”, and “Basic”. The password requirements for each policy are configurable (toggled on/off in the PingOne admin console), as are the password policy rules. When updating a password policy, the password policy rules are configurable by including or excluding the rule property or properties from the payload.

    Use Cases

    The pre-defined password policies have the following requirements:

    Policy Requirements
    Basic A relaxed standard policy to allow for maximum customer flexibility. The basic password policy does not have an expiration rule. When this password policy is in effect, user passwords do not expire. Requirements include:
    The password will be checked against a list of most commonly-used passwords.
    The password must be between 8 and 255 characters.
    The password must have at least 1 of the following characters: 1234567890
    The password must have at least 1 of the following characters: abcdefghijklmnopqrstuvwxyz
    The password must have at least 1 of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ
    The password must have at least 1 of the following characters: ~!@#$%^&*()-_=+[]{}
    The user's account will lockout after 5 failed attempts for 15 minutes. Repeated attempts of the same password will not be counted as failed attempts.
    Standard A standard password policy that incorporates industry best practices. Requirements include:
    The password will be checked to make sure it doesn't match strings that appear in the user's identity data.
    The password will be checked to make sure it is not too similar to the user's current password.
    The password will be checked against a list of most commonly-used passwords.
    The password cannot have more than 2 repeated characters.
    The password must have a minimum of 5 unique characters.
    The password must be between 8 and 255 characters.
    The password must have at least 1 of the following characters: 1234567890
    The password must have at least 1 of the following characters: abcdefghijklmnopqrstuvwxyz
    The password must have at least 1 of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ* The password must have at least 1 of the following characters: ~!@#$%^&*()-_=+[]{}
    The password will expire every 182 days.
    Passwords can be changed after 1 day.
    6 prior passwords will be maintained in the password history count for a maximum of 365 days.
    The user's account will lockout after 5 failed attempts for 15 minutes. Repeated attempts of the same password will not be counted as failed attempts.
    Passphrase A password policy that accepts the use of passphrases. Requirements include:
    The password will be checked to make sure it doesn't match strings that appear in the user's identity data.
    The password will be checked to make sure it is not too similar to the user's current password.
    The password will be checked against a list of most commonly-used passwords.
    The password must have a complexity of at least 7 days, based on the Gibson Research Corporation Password Haystacks concept.
    The password will expire every 182 days.
    Passwords can be changed after 1 day.
    6 prior passwords will be maintained in the password history count for a maximum of 365 days.

    For information about the specific password property values set for each pre-defined password policy, see the response data for Read All Password Policies.

    Password policies data model

    Property Type Required? Mutable? Description
    alphabetSequenceRule.maxLength Integer Optional Mutable Maximum number of allowed sequential English letters in the password. Must be a value of 2 or 3.
    bypassPolicy Boolean Optional Mutable Determines whether the password policy for a user will be ignored. If this property is omitted from a Create Password Policy request, its value is set to false.
    createdAt Date Required Immutable The date and time the resource was created (format ISO-8061).
    default Boolean Optional Mutable Indicates whether this password policy is enforced within the environment. When set to true, all other password policies are set to false.
    description String Optional Mutable Specifies the brief description of the password policy.
    environment.id String Required Immutable The ID of the environment resource referenced by this relationship.
    excludesCommonlyUsed Boolean Optional Mutable Set this to true to ensure the password is not one of the commonly used passwords.
    excludesProfileData Boolean Optional Mutable Set this to true to ensure the password is not an exact match for the value of any attribute in the user’s profile, such as name, phone number, or address.
    history.count Integer Optional Mutable Specifies the number of prior passwords to keep for prevention of password re-use. The value must be a positive, non-zero integer.
    history.retentionDays Integer Optional Mutable The length of time to keep recent passwords for prevention of password re-use. The value must be a positive, non-zero integer.
    id String Required Immutable The password resource’s unique identifier.
    length.max Integer Optional Mutable The maximum number of characters allowed for the password. Defaults to 255. This property is not enforced when not present.
    length.min Integer Optional Mutable The minimum number of characters required for the password. This can be from 8 to 32 (inclusive). Defaults to 8 characters. This property is not enforced when not present.
    lockout.durationSeconds Integer Optional Mutable The length of time before a password is automatically moved out of the lock out state. The value must be a positive, non-zero integer.
    lockout.failureCount Integer Optional Mutable The number of tries before a password is placed in the lockout state. The value must be a positive, non-zero integer.
    maxAgeDays Integer Optional Mutable The maximum number of days the same password can be used before it must be changed. Defaults to 90 days. When the maxAgeDays value is reached, it automatically resets to the assigned value. The value must be a positive, non-zero integer.
    The value must be greater than the sum of minAgeDays (if set) + 21 (the expiration warning interval for passwords).
    maxRepeatedCharacters Integer Optional Mutable The maximum number of repeated characters allowed. This property is not enforced when not present.
    minAgeDays Integer Optional Mutable The minimum number of days a password must be used before changing. The value must be a positive, non-zero integer. This property is not enforced when not present.
    minCharacters Object Optional Mutable Contains name-value pairs where the name includes all characters in the set, and the value is the minimum number of times one of the characters in the set must appear in the password. The only allowed keys are ABCDEFGHIJKLMNOPQRSTUVWXYZ, abcdefghijklmnopqrstuvwxyz, 0123456789, and ~!@#$%^&*()-_=+[]{}|;:,.<>/?. This property is not enforced when not present.
    minComplexity Integer Optional Mutable The minimum complexity of the password based on the concept of password haystacks. The value is the number of days required to exhaust the entire search space during a brute force attack. This property is not enforced when not present.
    minUniqueCharacters Integer Optional Mutable The minimum number of unique characters required. This property is not enforced when not present.
    name String Optional Mutable The name of the password policy. This value must be unique within the environment.
    notSimilarToCurrent Boolean Optional Mutable Set this to true to ensure that the proposed password is not too similar to the user's current password based on the Levenshtein distance algorithm. The value of this parameter is evaluated only for password change actions in which the user enters both the current and the new password. By design, PingOne does not know the user's current password.
    numberSequenceRule.maxLength Integer Optional Mutable Maximum number of allowed sequential numbers in the password. Must be a value of 2 or 3.
    shiftedNumberRowSequenceRule.maxLength Integer Optional Mutable Maximum number of allowed sequential symbol row characters. Must be a value of 3.
    populationCount Integer Required Immutable Returned in the response. The number of populations associated with the password policy.
    updatedAt Date Required Immutable The date and time the resource was last updated (format ISO-8061).
    qwertySequenceRule.maxLength Integer Optional Mutable Maximum number of allowed sequential QWERTY keyboard characters in the password. Must be a value of 3.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    password-policies POLICY.UPDATED

    Response codes

    Code Message
    200 Successful operation.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Create Password Policy

    Read All Password Policies

    Read One Password Policy

    Update Password Policy

    Delete Password Policy

    Schemas

    The schemas endpoints give administrators the ability to customize the existing attributes of the user model or define new attributes that are not part of the default user model. For example, applications often support user profile attributes that are not defined in the PingOne core attribute set for users.

    For more information about schemas, see User Attributes in the PingOne Admin Guide.

    Attribute types

    There are three types of attributes that the user schema supports: core, standard, and custom. Core and standard attributes are available in the out-of-the-box user schema, and these attributes cannot be deleted. Custom attributes can be created, updated, and deleted. All types of attributes can be retrieved from a GET operation.

    The mutability rules for these three types of attributes are:

    • Core attributes (for example, id or username) cannot be modified in any way.
    • Standard attributes (for example, email, preferred language, address) cannot be modified except to configure these flags: enabled and unique.
    • Custom attributes (for example, ssn or shirtSize) can be modified except for the name, type and schema properties. The multiValued property of custom attributes can only be changed from false or null to true. The required property is ignored if included in a create request body (defaults to false) and returns an error if included in an update request body.

    The schemas service supports the following capabilities:

    • The ability to use out-of-the-box user schema custom attributes.
    • The ability to select a subset of the PingOne standard schema that is relevant for users stored in an environment.
    • The ability to add custom attributes to the schema that are used for the same purposes as PingOne default attributes.
    • The ability to add custom attributes that support multiple values.
    • The ability to define the behavior and data requirements of special attributes such as passwords, usernames, email addresses, and phone numbers.

    The request examples show common actions for working with schema resources and custom attributes. You need the Environment Admin role to read and update schema resources. Administrators with the Identity Data Admin or Client Application Developer roles can read schema resources.

    Custom attributes

    Custom attributes convey additional information about the user to applications. You can add custom attributes to the user schema to identify and store key information such as account numbers, user preferences, demographic information, and other relevant profile data required by the application. A custom attribute is a name-value pair that can reference JSON or STRING user schema attributes or a static value.

    If the custom attribute has multiple values, then the attribute will be multi-valued in the token or assertion as well. This is calculated based on the string length for all of the custom attribute values. For example, given:

    { "id": "1234", "username": "jdoe", "customA": "1234", "customB": "1234" }

    The cumulative custom attribute size in this case is 8. Size calculations for multi-valued and JSON custom attributes are the same. For the multi-valued custom attributes, add the length of all of the array elements. For JSON custom attributes, add the length of the JSON string. You can add a maximum of 200 custom string attributes and 200 custom JSON attributes. Bear in mind that the maximum size of the entire user profile is 16 Kb.

    An attribute can support multiple values if the multiValued property is set to true. If the multiValued property is set to false or is null, the User object will contain the attribute value as a single value. If multiValued is set to true, the value in the User object will be an array. When searches are performed on User schema data, a user will match if any value of a multiValued attribute is part of the search criteria.

    Reserved attribute names

    The following attribute names are reserved for internal use. Custom attributes cannot have the same name as these reserved attribute names.

    • password
    • devices
    • roleAssignments
    • pairingCodes
    • linkedAccounts
    • environment
    • population
    • account

    Enumerated values and regular expressions

    An attribute is enumerated if the attributes.enumeratedValues[] property is present and has at least one unarchived attributes.enumeratedValues[].value. An attributes.enumeratedValues[].value cannot be deleted, but it can be archived. If all attributes.enumeratedValues[].value objects are archived, the attributes.enumeratedValues[] property is removed from the attribute. An existing attribute cannot be made enumerated. It is possible to add attributes.enumeratedValues[] objects to an existing enumerated attribute and to unarchive existing archived values.

    A regular expression can be added to an attribute to validate the client-provided value. An attribute cannot be both regex and enumerated. However, a value matching a regular expression can be multi-valued or unique. A list of test case values that the pattern should match and should not match can also be provided to help validate that the pattern is correct.

    Schema attributes POST, PUT, PATCH data model

    Property Type Required? Mutable? Description
    description String Optional Mutable A description of the attribute. If provided, it must not be an empty string. Valid characters consists of any Unicode letter, mark (for example, accent or umlaut), numeric character, punctuation character, or space.
    displayName String Optional Mutable The display name of the attribute such as 'T-shirt size’. If provided, it must not be an empty string. Valid characters consist of any Unicode letter, mark (for example, accent or umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
    enabled Boolean Required Mutable Indicates whether or not the attribute is enabled. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null. Disabled attributes are ignored for POST or PUT, and are not returned for GET operations.
    enumeratedValues[] Array Optional Mutable An array of enumerated values. Maximum number of enumerations is 100.
    enumeratedValues[].value String Required Mutable A string that specifies the immutable value. Values are case sensitive; two values that differ only by case are not allowed. Required if enumeratedValues[] is set.
    enumeratedValues[].archived Boolean Optional Mutable A boolean that specifies whether the enumerated value is archived. Archived values cannot be added to a user, but existing archived values are preserved. This allows clients that read the schema to know all possible values of an attribute.
    enumeratedValues[].description String Optional Mutable A string that specifies the description of the enumerated value.
    environment.id String N/A Immutable The identifier of the environment resource referenced by this relationship.
    id String N/A Immutable The attribute’s unique identifier.
    ldapAttribute String Required Immutable The unique identifier for the LDAP attribute.
    multiValued Boolean Optional Mutable A boolean that specifies whether the attribute has multiple values or a single one. This value can only change from false to true, as changing from true to false is not allowed. Maximum number of values stored is 1,000.
    name String Required Mutable The name of the attribute. The attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must also be unique within the schema for an environment. It must start with a letter and may be followed by letters, numbers or hyphens.
    regexValidation Object Optional Mutable Object representation of the optional regular expression representation of this attribute.
    regexValidation.pattern String Required Mutable A string that specifies the regular expression to which the attribute must conform. Required if regexValidation is set.
    regexValidation.requirements String Required Mutable A string that specifies a developer friendly description of the regular expression requirements. Required if regexValidation is set.
    regexValidation.valuesPatternShouldMatch Array Optional Mutable An array that specifies the list of strings matching the regular expression.
    regexValidation.valuesPatternShouldNotMatch Array Optional Mutable An array that specifies the list of strings not matching the regular expression.
    required Boolean N/A Read only Indicates whether or not the attribute is required. The value of this property for custom attributes is always false.
    schema.id String Required Immutable The identifier of the resource referenced by this relationship.
    schemaType String Required Mutable The schema type of the attribute. This can be CORE, STANDARD or CUSTOM. CORE and STANDARD attributes are supplied by default. CORE attributes cannot be updated or deleted. STANDARD attributes cannot be deleted, but their mutable properties can be updated. CUSTOM attributes can be deleted, and their mutable properties can be updated. New attributes are created with a schema type of CUSTOM.
    subAttributes Array Optional Mutable The list of sub-attributes of this attribute. Only COMPLEX attribute types can have sub-attributes, and only one-level of nesting is allowed. The leaf attribute definition must have a type of STRING or JSON. A COMPLEX attribute definition must have at least one child attribute definition.
    subAttributes.description String Optional Mutable A description of the sub-attribute. If provided, it must not be an empty string. Valid characters consists of any Unicode letter, mark (for example, accent or umlaut), numeric character, punctuation character, or space.
    subAttributes.displayName String Optional Mutable The display name of the sub-attribute such as 'T-shirt size’. If provided, it must not be an empty string. Valid characters consist of any Unicode letter, mark (for example, accent or umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
    subAttributes.enabled Boolean Required Mutable Indicates whether or not the sub-attribute is enabled. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null. Disabled sub-attributes are ignored for POST or PUT, and are not returned for GET operations.
    subAttributes.name String Required Mutable The name of the sub-attribute. The sub-attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must start with a letter and may be followed by letters, numbers or hyphens.
    subAttributes.required Boolean Optional Mutable Indicates whether or not the sub-attribute is required. Required attributes must be provided a value for POST and PUT. Defaults to false.
    subAttributes.schemaType String Required Mutable The schema type of the sub-attribute. This can be CORE, STANDARD or CUSTOM. CORE and STANDARD sub-attributes are supplied by default. CORE sub-attributes cannot be updated or deleted. STANDARD sub-attributes cannot be deleted, but their mutable properties can be updated. CUSTOM sub-attributes can be deleted, and their mutable properties can be updated. New sub-attributes are created with a schema type of CUSTOM.
    subAttributes.type String Optional Mutable The type of the sub-attribute. This can be STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, it defaults to STRING. COMPLEX and BOOLEAN sub-attributes cannot be created, but standard sub-attributes of those types may be updated. JSON sub-attributes are limited by size (total size must not exceed 16KB).
    subAttributes.unique Boolean Required Mutable Indicates whether or not the sub-attribute must have a unique value within the PingOne environment. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null.
    type String Optional Mutable The type of the attribute. This can be STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, it defaults to STRING. COMPLEX and BOOLEAN attributes cannot be created, but standard attributes of those types may be updated. JSON attributes are limited by size (total size must not exceed 16KB).
    unique Boolean Required Mutable Indicates whether or not the attribute must have a unique value within the PingOne environment. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null.

    Schema attributes GET response model

    Property Type Required? Mutable? Description
    attributes.description String Optional Mutable A description of the attribute. If provided, it must not be an empty string. Valid characters consists of any Unicode letter, mark (for example, accent or umlaut), numeric character, punctuation character, or space.
    attributes.displayName String Optional Mutable The display name of the attribute such as 'T-shirt size’. If provided, it must not be an empty string. Valid characters consist of any Unicode letter, mark (for example, accent or umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
    attributes.enabled Boolean Required Mutable Indicates whether or not the attribute is enabled. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null. Disabled attributes are ignored for POST or PUT, and are not returned for GET operations.
    attributes.environment.id String N/A Immutable The identifier of the environment resource referenced by this relationship.
    attributes.id String N/A Immutable The attribute’s unique identifier.
    attributes.ldapAttribute String Required Immutable The unique identifier for the LDAP attribute.
    attributes.multiValued Boolean Optional Mutable A boolean that specifies whether the attribute has multiple values or a single one. This value can only change from false to true, as changing from true to false is not allowed. Maximum number of values stored is 1,000.
    attributes.name String Required Mutable The name of the attribute. The attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must also be unique within the schema for an environment. It must start with a letter and may be followed by letters, numbers or hyphens.
    attributes.regexValidation Object Optional Mutable Object representation of the optional regular expression representation of this attribute.
    attributes.regexValidation.pattern String Required Mutable A string that specifies the regular expression to which the attribute must conform. Required if attributes.regexValidation is set.
    attributes.regexValidation.requirements String Required Mutable A string that specifies a developer friendly description of the regular expression requirements. Required if attributes.regexValidation is set.
    attributes.regexValidation.valuesPatternShouldMatch Array Optional Mutable An array that specifies the list of strings matching the regular expression.
    attributes.regexValidation.valuesPatternShouldNotMatch Array Optional Mutable An array that specifies the list of strings not matching the regular expression.
    attributes.required Boolean Optional Mutable Indicates whether or not the attribute is required. Required attributes must be provided a value for POST and PUT. Defaults to false.
    attributes.schema.id String Required Immutable The identifier of the resource referenced by this relationship.
    attributes.schemaType String Required Mutable The schema type of the attribute. This can be CORE, STANDARD or CUSTOM. CORE and STANDARD attributes are supplied by default. CORE attributes cannot be updated or deleted. STANDARD attributes cannot be deleted, but their mutable properties can be updated. CUSTOM attributes can be deleted, and their mutable properties can be updated. New attributes are created with a schema type of CUSTOM.
    attributes.type String Optional Mutable The type of the attribute. This can be STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, it defaults to STRING. COMPLEX and BOOLEAN attributes cannot be created, but standard attributes of those types may be updated. JSON attributes are limited by size (total size must not exceed 16KB).
    attributes.unique Boolean Required Mutable Indicates whether or not the attribute must have a unique value within the PingOne environment. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null.
    attributes.subAttributes Array Optional Mutable The list of sub-attributes of this attribute. Only COMPLEX attribute types can have sub-attributes, and only one-level of nesting is allowed. The leaf attribute definition must have a type of STRING or JSON. A COMPLEX attribute definition must have at least one child attribute definition.
    attributes.subAttributes.description String Optional Mutable A description of the sub-attribute. If provided, it must not be an empty string. Valid characters consists of any Unicode letter, mark (for example, accent or umlaut), numeric character, punctuation character, or space.
    attributes.subAttributes.displayName String Optional Mutable The display name of the sub-attribute such as 'T-shirt size’. If provided, it must not be an empty string. Valid characters consist of any Unicode letter, mark (for example, accent or umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
    attributes.subAttributes.enabled Boolean Required Mutable Indicates whether or not the sub-attribute is enabled. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null. Disabled sub-attributes are ignored for POST or PUT, and are not returned for GET operations.
    attributes.subAttributes.name String Required Mutable The name of the sub-attribute. The sub-attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must start with a letter and may be followed by letters, numbers or hyphens.
    attributes.subAttributes.required Boolean Optional Mutable Indicates whether or not the sub-attribute is required. Required attributes must be provided a value for POST and PUT. Defaults to false.
    attributes.subAttributes.schemaType String Required Mutable The schema type of the sub-attribute. This can be CORE, STANDARD or CUSTOM. CORE and STANDARD sub-attributes are supplied by default. CORE sub-attributes cannot be updated or deleted. STANDARD sub-attributes cannot be deleted, but their mutable properties can be updated. CUSTOM sub-attributes can be deleted, and their mutable properties can be updated. New sub-attributes are created with a schema type of CUSTOM.
    attributes.subAttributes.type String Optional Mutable The type of the sub-attribute. This can be STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, it defaults to STRING. COMPLEX and BOOLEAN sub-attributes cannot be created, but standard sub-attributes of those types may be updated. JSON sub-attributes are limited by size (total size must not exceed 16KB).
    attributes.subAttributes.unique Boolean Required Mutable Indicates whether or not the sub-attribute must have a unique value within the PingOne environment. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null.
    description String Optional Mutable The description of the attribute.
    displayName String Optional Mutable The display name of the attribute such as 'T-shirt size’. If provided, it must not be an empty string. Valid characters consist of any Unicode letter, mark (for example, accent or umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
    enabled Boolean Required Mutable Indicates whether or not the attribute is enabled. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null. Disabled attributes are ignored for POST or PUT, and are not returned for GET operations.
    environment.id String N/A Immutable The environment resource’s unique identifier.
    id String Required Immutable The attribute's unique identifier.
    multiValued Boolean Optional Mutable A boolean that specifies whether the attribute has multiple values or a single one. This value can only change from false to true, as changing from true to false is not allowed. Maximum number of values stored is 1,000.
    name String Required Mutable The attribute name.
    required Boolean Optional Mutable Indicates whether or not the attribute is required. Required attributes must be provided a value for POST and PUT. Defaults to false.
    schema.id String Optional Mutable The schema's unique identifier.
    schemaType String Required Mutable The schema type of the attribute. This can be CORE, STANDARD or CUSTOM. CORE and STANDARD attributes are supplied by default. CORE attributes cannot be updated or deleted. STANDARD attributes cannot be deleted, but their mutable properties can be updated. CUSTOM attributes can be deleted, and their mutable properties can be updated. New attributes are created with a schema type of CUSTOM.
    type String Optional Mutable The type of the attribute. This can be STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, it defaults to STRING. COMPLEX and BOOLEAN attributes cannot be created, but standard attributes of those types may be updated. JSON attributes are limited by size (total size must not exceed 16KB).
    unique Boolean Required Mutable Indicates whether or not the attribute must have a unique value within the PingOne environment. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null.

    Schemas GET response model

    Property Type Required? Mutable? Description
    description String Optional Mutable The description of the schema.
    environment.id String N/A Immutable The environment resource’s unique identifier.
    id String Required Immutable The schema’s unique identifier.
    name String Required Mutable The schema name.
    schemas.description String Optional Mutable The description of the schema.
    schemas.environment.id String Optional Mutable The unique identifier of the environment containing the schema.
    schemas.id String Optional Mutable The schema's unique identifier.
    schemas.name String Required Mutable The schema name.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    schemas ATTRIBUTE.CREATED
    schemas ATTRIBUTE.UPDATED
    schemas ATTRIBUTE.DELETED

    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.
    404 The requested resource was not found.

    Create Attribute

    Read All Schemas

    Read All (Schema) Attributes

    Read One Schema

    Read One Attribute

    Update Attribute (Put)

    Update Attribute (Patch)

    Delete Attribute

    Users

    A user is any end-user of the applications and services provided by the PingOne platform. Workforce users, customers, and admins are all user types. Each user is a resource with a unique identity that interacts with the applications and services in your PingOne environment.

    Every user is associated with a PingOne environment and a user population.

    The Users service lets you create, read, update, and delete user resources. You can manage user group membership, passwords, admin roles, and manage associations with external identity providers (IdPs).

    • For more information about user management, see Users in the PingOne Admin Guide.

    • Managing user accounts

      The base endpoint, /environment/{{envID}}/users, enables directory operations to create and manage user accounts, including assigning the user to a population, assigning user roles, and unlocking a user account. It also supports an import capability that gives privileged applications the ability to create a new user and set the user's password.

      For more information, see:

    • Password management

      The password management endpoints provide functions to set, update, unlock, and recover a user's password.

      For more information, see User Passwords.

    • MFA device management

      The multi-factor authentication (MFA) device endpoints enable the user's MFA capability and specify MFA devices associated with the user account.

      For more information, see:

    • User agreement consent management

      The /environments/{{envID}}/users/{{userID}}/agreementConsents endpoint provides directory operations to read, accept, and revoke an agreement associated with a user account.

      For more information, see User Agreement Consents.

    • User ID verification

      The /environments/{{envID}}/users/{{userID}}/verifyTransactions endpoint provides directory operations to create, read, update, and delete an ID verification transaction record associated with a user.

      For more information, see PingOne Verify.

    You must have the Identity Data Admin role to perform operations on users resources.

    Use Cases

    User operations

    The users endpoint provides operations to create, read, update, and delete users. It includes an import operation that gives privileged applications the ability to create a new user and set the user's password as part of the user create operation. It also includes endpoints for user verification actions.

    Users data model

    Property Type Required? Mutable? Description
    account.canAuthenticate Boolean Required Mutable Whether the user can authenticate. If the value is set to false, the account is locked or the user is disabled, and unless specified otherwise in administrative configuration, the user will be unable to authenticate.
    account.lockedAt Date N/A Read-only The time the specified user account was locked. This property might be absent if the account is unlocked or if the account was locked out automatically by failed password attempts.
    account.secondsUntilUnlock Integer N/A Read-only The number of seconds until the user's account is unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).
    account.status String Required Mutable The account locked state. Options are LOCKED and OK.
    account.unlockAt Date N/A Read-only The time the specified user account will be unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock and must be unlocked by an administrator.
    address.countryCode String Optional Mutable The country name component. When specified, the value must be in ISO 3166-1 “alpha-2” code format. For example, the country codes for the United States and Sweden are “US” and "SE", respectively. Valid characters consist of two upper-case letters (regex: [A-Z]{2}).
    address.locality String Optional Mutable The city or locality component of the address. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    address.postalCode String Optional Mutable The ZIP code or postal code component of the address. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 40 characters (min/max=1/40).
    address.region String Optional Mutable The state, province, or region component of the address. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    address.streetAddress String Optional Mutable The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute may contain newlines (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}\n\r]*$). It can have a length of no more than 256 characters (min/max=1/256).
    bypassMFAEnabledUntil Date Required Mutable Used to define a period during which the user can bypass MFA. For details, see Allow MFA Bypass for User.
    canBypassMFA Boolean N/A Read-only Indicates whether the user currently has permission to bypass MFA.
    createdAt Date N/A Read-only The time the resource was created.
    email String Required Mutable The user’s email address, which must be provided and valid. For more information about email address formatting, see section 3.4 of RFC 2822, Internet Message Format.
    emailVerified Boolean Optional Mutable Whether the user’s email is verified, either as part of account verification (see VERIFICATION_REQUIRED in the lifecycle.status property), or as the result of a separate email verification process (see Verify Email (Code)).
    enabled Boolean N/A Read-only Whether the user is enabled. This attribute is set to ‘true’ by default when the user is created.
    environment.id String N/A Read-only The environment resource’s unique identifier associated with the user.
    externalId String Optional Mutable An identifier for the user resource as defined by the provisioning client. This may be explicitly set to null when updating a user to unset it. The externalId attribute simplifies the correlation of the user in PingOne with the user’s account in another system of record. The platform does not use this attribute directly in any way, but it is used by Ping Identity’s Data Sync product. It can have a length of no more than 1024 characters (min/max=1/1024).
    groupMemberships.type String Optional Immutable Whether the user is a member of a group through direct assignment or indirect filtering: DIRECT or INDIRECT.
    id String N/A Read-Only The user resource’s unique identifier.
    identityProvider.id String Required/Optional Mutable Identifies the external identity provider used to authenticate the user. If not provided, PingOne is the identity provider. This attribute is required if the identity provider is authoritative for just-in-time user provisioning.
    identityProvider.type String N/A Read-Only Identifies the type of identity provider used to authenticate the user. Possible values are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, SAML, and PING_ONE. The default value of PING_ONE is set when a value for identityProvider.id is not provided. The PING_ONE value is the default for all pre-existing users. There is currently no search filter support for this attribute.
    invite Object N/A Read-only The invitation resource. Applicable only when a user record represents an invite.
    invite.expiresAt String N/A Read-only Date value for when the invite expires.
    lastSignOn.at Date N/A Read-only The time of the last successful login of the user through the PingOne flow API.
    lastSignOn.remoteIp String N/A Read-only The IP address of the last successful login of the user through the PingOne flow API.
    lifecycle.status String Optional Mutable The status of the account lifecycle. Options are ACCOUNT_OK and VERIFICATION_REQUIRED. This property can only be set when importing a user to set the initial account status. If omitted, the account status defaults to ACCOUNT_OK. When the initial status is set to VERIFICATION_REQUIRED, an email address is required and a verification email is sent to the email address provided. The verification code must be entered the first time the user tries to authenticate and does not expire when used for this purpose. As a result of using the verification code, the value transitions to ACCOUNT_OK. If the verification code is used within 24 hours, emailVerified was set to false, and the user's email has not changed, emailVerified also transitions to true.
    lifecycle.suppressVerificationCode Boolean Optional Write-Only Used when importing a user and the lifecycle.status is set to VERIFICATION_REQUIRED. If this property is set to true, no verification email is sent to the user. If this property is omitted or set to false, a verification email is sent to the user automatically.
    locale String Optional Mutable The user’s default location. This may be explicitly set to null when updating a user to unset it. This is used for purposes of localizing such items as currency, date time format, or numerical representations. If provided, it must be a valid language tag as defined in RFC 5646. The following are example tags: fr, en-US, es-419, az-Arab, man-Nkoo-GN. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    memberOfAdminGroup Array Optional Read-only A list of groups with admin roles that include the user. Only returned when the include=memberOfAdminGroup query parameter is appended to the request URL.
    memberOfExternalGroups Object[] Optional Mutable This is used only for Just In Time (JIT) creation of external groups.
    memberOfExternalGroups.name String Required Mutable The name of the external group as it exists in the source.
    memberOfExternalGroups.sourceId String Required Mutable The ID of the external group as it exists in the source (generally a UUID).
    memberOfExternalGroups.sourceType String Required Mutable The type of the external group as it exists in the source. Currently, this can be only "GATEWAY" or "IDP".
    memberOfGroupIDs Array Optional Read-only IDs for the groups the user is a member of. This property is returned for GET {{apiPath}}/environments/{{envID}}/users/{{userID}} when the include=memberOfGroupIDs query parameter is appended to the request. This property is not returned with a list of users.
    memberOfGroupNames Array Optional Read-only Names for the groups the user is a member of. This property is returned for GET {{apiPath}}/environments/{{envID}}/users/{{userID}} when the include=memberOfGroupNames query parameter is appended to the request. This property is not returned with a list of users.
    mfaEnabled Boolean Optional Mutable Whether multi-factor authentication is enabled. This attribute is set to false by default when the user is created. You can set mfaEnabled to true with POST Create User, POST Create User (Import), or PUT Update User MFA Enabled. You cannot update mfaEnabled with PUT Update User or PATCH Update User.
    mobilePhone String Optional Mutable The user’s native phone number. This might also match the primaryPhone attribute. This may be explicitly set to null when updating a user to unset it. Valid phone numbers must have at least one number and a maximum character length of 32.
    name.family String Optional Mutable The family name of the user, or Last in most Western languages (for example, ‘Jensen’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen (regex: ^[\p{L}\p{M}\p{N}' .-]*$). It can have a length of no more than 256 characters (min/max=1/256).
    name.formatted String Optional Mutable The fully formatted name of the user (for example ‘Ms. Barbara J Jensen, III’). This can be explicitly set to null when updating a name to unset it. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen (regex: ^[\p{L}\p{M}\p{N}' .-]*$). It can have a length of no more than 256 characters (min/max=1/256).
    name.given String Optional Mutable The given name of the user, or First in most Western languages (for example, ‘Barbara’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    name.honorificPrefix String Optional Mutable The honorific prefix(es) of the user, or title in most Western languages (for example, ‘Ms.’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
    name.honorificSuffix String Optional Mutable The honorific suffix(es) of the user, or suffix in most Western languages (for example, ‘III’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
    name.middle String Optional Mutable The the middle name(s) of the user (for exmple, ‘Jane’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    nickname String Optional Mutable The user’s nickname. This can be explicitly set to null when updating a user to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    Operations Array Optional Mutable A JSON array that specifies modifications to users schema attributes in a SCIM PATCH request. The Operations property is not valid in a regular PATCH request.
    Operations.op String Optional Mutable The update operation type. Options are add, replace, and remove. The Operations property can have one or more operations.op attributes specified in the request body.
    Operations.path String Optional Mutable The users schema attribute to be modified.
    Operations.value String Optional Mutable The updated value for the users schema attribute that is modified.
    password Object Optional Immutable An object that specifies the user's password. This property is never returned in the response.
    password.forceChange Boolean Optional Mutable Whether the user is forced to change the password on the next log in. If not provided, the property is set to false.
    password.value String Optional Immutable The user's password value. The string is either in cleartext or pre-encoded format.
    password.external Object Optional Immutable Maps the information relevant to the user’s password, and its association to external directories.
    password.external.
    gateway    		 Object Optional Mutable Contains the gateway properties. When this is value is specified, the user’s password is managed in an external directory. You can set the user password using Create User (Import) or Update Password (Set).
    password.external.
    gateway.id    		 String Optional Immutable The UUID of the linked gateway that references the remote directory.
    password.external.
    gateway.type    		 Enumeration Optional Mutable Indicates one of the supported gateway types. For the supported types, see type in the Gateway base data model.
    password.external.
    gateway.userType    		 String Optional Mutable A reference to a userType in the list of userTypes values for an LDAP gateway.
    password.external.
    gateway.userType.id    		 String Optional Immutable The UUID of a user type in the list of userTypes for the LDAP gateway.
    password.external.
    gateway.correlationAttributes    		 Object Optional Mutable Maps the external LDAP directory attributes to PingOne attributes. PingOne uses the correlationAttributes values to read the attributes from the external LDAP directory and map them to the corresponding PingOne attributes.
    photo.href String Optional Mutable The URI that is a uniform resource locator (as defined in Section 1.1.3 of RFC 3986) that points to a resource location representing the user’s image. This can be removed from a user by setting the photo attribute to null. If provided, the resource must be a file (for example, a GIF, JPEG, or PNG image file) rather than a web page containing an image. It must be a valid URL that starts with the HTTP or HTTPS scheme.
    population.id String Optional Immutable The identifier of the population resource associated with the user. This property cannot be updated using PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}. However, it can be updated using PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}/population.
    preferredLanguage String Optional Mutable The user’s preferred written or spoken languages. This may be explicitly set to null when updating a user to unset it. If provided, the format of the value must be a valid language range and the same as the HTTP Accept-Language header field (not including Accept-Language:) and is specified in Section 5.3.5 of RFC 7231. For example: en-US, en-gb;q=0.8, en;q=0.7.
    primaryPhone String Optional Mutable The user’s primary phone number. This might also match the mobilePhone attribute. This may be explicitly set to null when updating a user to unset it. Valid phone numbers must have at least one number and a maximum character length of 32.
    timezone String Optional Mutable The user’s time zone. This can be explicitly set to null when updating a user to unset it. If provided, it must conform with the IANA Time Zone database format RFC 6557, also known as the “Olson” time zone database format Olson-TZ for example, “America/Los_Angeles” (regex: ^\w+\/\w+$).
    title String Optional Mutable The user’s title, such as "Vice President". This can be explicitly set to null when updating a user to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    type String Optional Mutable The user’s type, which is optional. This can be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the PingOne platform. It could have values of "Contractor", "Employee", "Intern", "Temp", "External", and “Unknown”. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
    updatedAt Date N/A Read-only The time the resource was last updated.
    username String Required Mutable* The user name, which must be unique within an environment. This must either be a well-formed email address or another string. The string is case-insensitive, and can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). Any leading whitespace is ignored. The maximum length is 128 characters. *Note: This property is immutable when PingID is part of the environment.
    verifyStatus String Required Mutable Indicates whether ID verification can be done for the user. This value can be: NOT_INITIATED (the initial value), ENABLED, or DISABLED. If the user verification status is DISABLED, a new verification status cannot be created for that user until the status is changed to ENABLED.

    Limiting and Filtering data

    You can limit the number of results returned on the Read User or Users request with the limit parameter:

    https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users?limit=200

    See 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 User or Users request. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, this URL-encoded SCIM filter returns up to 200 members of the population with an ID of 60971d3b-cc5a-4601-9c44-2be541f91bf1:

    https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users?limit=200&filter=population.id eq "60971d3b-cc5a-4601-9c44-2be541f91bf1"

    These SCIM operators can be applied to the following attributes:

    • eq (equals)

      Supported attributes: accountId, address.streetAddress, address.locality, address.region, address.postalCode, address.countryCode, email, enabled, endDate, externalId, locale, mobilePhone, name.formatted, name.given, name.middle, name.family, name.honorificPrefix, name.honorificSuffix, nickname, population.id, photo.href, preferredLanguage, primaryPhone, startDate, timezone, title, type, username, and custom attributes of type STRING

    • sw (starts with)

      Supported attributes: accountId, address.streetAddress, address.locality, address.region, address.postalCode, address.countryCode, email, enabled, externalId, locale, mobilePhone, name.formatted, name.given, name.middle, name.family, name.honorificPrefix, name.honorificSuffix, nickname, photo.href, preferredLanguage, primaryPhone, timezone, title, type, username, and custom attributes of type STRING

    • ew (ends with)

      Supported attributes: name.given, name.family, email (only for the domain specified in the address, starting with and including the symbol "@", such as "@example.com").

    • and (logical AND)

      Logical AND for building compound expressions in which both expressions are true.

    • or (logical OR)

      Logical OR for building compound expressions if either expression is true.

    • co (contains)

      Supported attributes: name.given, name.family.

    These SCIM operators are not supported: ne (not equal), pr (present, is a non-empty or non-null value), gt (greater than), ge (greater than or equal to), lt (less than), le (less than or equal to), not (logical NOT). The API does not support empty strings in a sw filtering expression. If empty strings are submitted in the request, the response returns a 400 FAILED_REQUEST with an INVALID_FILTER detail error.

    You can also use custom user schema string attributes in a filtering expression to fine-tune the user response data. For more information about custom attributes, see Schemas. For more information about SCIM syntax and operators, see Conventions.

    Expanding user population information

    The GET {{apiPath}}/environments/{{envID}}/users and GET {{apiPath}}/environments/{{envID}}/users/{{userID}} endpoints allow an expand query parameter on the population embedded resource. A query that expands population returns information about a user's associated population as an _embedded resource.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    users USER.CREATED
    users USER.DELETED
    users USER.LOCKED
    users USER.MOVED
    users USER.UNLOCKED
    users USER.UPDATED
    users USER.ACCESS.ALLOWED
    users USER.ACCESS.DENIED

    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.
    404 The requested resource was not found.

    Create User

    Create User (Import)

    Create User Import External Password

    Verify User

    Send/Resend User Verification Code

    Update User

    Update User

    Update User Using JSON Array

    Read User or Users

    Read User by ID

    Read User Identity Provider

    Update User Identity Provider

    Delete User

    Group Membership

    For information about groups, including adding users to groups and removing users from groups, see Groups.

    Add User to Group

    Remove User from Group

    Read All Users in a Group

    Read All Users in Multiple Groups

    Read All Users in a Group with Other User Attribute

    Read All Group Names for User

    Read All Group IDs for User

    Read All Group Memberships for User

    Read One Group Membership for User

    Enable Users

    The enable user settings control whether a user's ability to authenticate is activated or deactivated. This endpoint gives administrators the ability to turn on (or off) a user's active status.

    For information about users, see Users.

    Enable user data model
    Property Type Required? Mutable? Description
    enabled Boolean Required Mutable Specifies whether the user is enabled. This attribute is set to true by default when the user is created.
    id String Required Mutable Specifies the user resource’s unique identifier.
    Response codes
    Code Message
    200 Successful operation.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Read User Enabled

    Update User Enabled

    Linked Accounts

    The linked accounts endpoints manage a user’s account links to external identity provider accounts. In an authentication flow, after successful authentication at the external identity provider, a linked account resource is created to establish the connection between the user resource in the PingOne directory and that user's external identity provider account. These endpoints can also be used to view and remove linked accounts in delegated administration or self-service cases.

    Users linked accounts request data model

    Property Type Required? Mutable? Description
    attributes.{{attributeName}} Object Optional Mutable An object that specifies an optional user attribute to update when linking the user. These are mapped user attribute names and values from the external identity provider that are used to update the user.
    externalId String Required Mutable A string that specifies the external ID, which is the identifier for the user's external identity provider account.
    identityProvider.id String Required Mutable A string that specifies the external identity provider ID associated with the user to which the user has a linked account.

    Users linked accounts response data model

    Property Type Required? Mutable? Description
    environment.id String Required Read-only A string that specifies the environment associated with the user's linked account.
    externalId String Required Read-only A string that specifies the external ID, which is the identifier for the user's external identity provider account.
    id String Required Read-only A string that specifies the linked account ID associated with the user resource ID identified in the request URL.
    identityProvider.id String Required Read-only A string that specifies the external identity provider ID associated with the user to which the user has a linked account.
    user Object Required Read-only An _embedded object that specifies the user associated with the linked account.
    user.id String Required Read-only A string that specifies the user ID associated with the linked account.

    Response codes

    Code Message
    200 Successful operation.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    For linked accounts endpoint operations, you need the Identity Data Admin role to get or delete linked account resources.

    Create Linked Account

    Read Linked Accounts

    Read One Linked Account

    Delete Linked Account

    User Populations

    The user populations endpoint supports operations to read and update the population associated with a specified user.

    Users data model
    Property Type Required? Mutable? Description
    id String Required Mutable Specifies the population ID associated with the user resource ID identified in the request URL.
    Response codes
    Code Message
    200 Successful operation.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Read User Population

    Update User Population

    User Passwords

    The password management endpoints provide functions that enable the following operations on a specified user:

    • Get a user's password state
    • Validate a user's password
    • Set a user's password
    • Update a user's password
    • Unlock a user's password
    • Recover a forgotten password

    Password state data model

    Property Type Required? Mutable? Description
    environment.id String Required Mutable Specifies the ID of the environment resource referenced by this relationship.
    currentPassword String Required Mutable The current password to be verified before the new password is set. Required for self-change when the user already has a password (the user whose password is being changed is the same as the actor in the access token).
    lastChangedAt DateTime N/A Read-only The time the password was last changed. This property is not returned if the user does not have a password.
    newPassword String Optional Mutable The new password (must satisfy all requirements).
    passwordPolicy.id String N/A Read-only Specifies the ID of the password policy resource referenced by this relationship.
    secondsUntilUnlock Integer N/A Read-only Specifies the number of seconds before the password may be used again after a lock out. If absent, the password must be reset by an administrator before it may be used again after a lockout.
    status String N/A Read-only Specifies the current status of the password. Options are OK, NO_PASSWORD, PASSWORD_EXPIRED, PASSWORD_LOCKED_OUT, MUST_CHANGE_PASSWORD, and EXTERNAL. For more information, see the "Password status states" table below.
    user.id String Required Mutable Specifies the ID of the user resource referenced by this relationship.
    warnings.expires Object N/A Read-only Warns that the password will expire on the specified date and time. The warning will only display if the password will expire in less than 21 days.
    warnings.failuresRemaining Object N/A Read-only Warns that the password has been checked unsuccessfully and the user will be locked out after the indicated number of further unsuccessful attempts.
    warnings.noChangeUntil Object N/A Read-only Warns that the password was recently self-changed and cannot be self-changed again until the specified date and time.

    Password status states

    Password state Description
    NO_PASSWORD Specifies that no password has been set. It also indicates that the user does not use a password for authentication.
    OK Specifies that a password has been set and can be used for login actions.
    PASSWORD_EXPIRED Specifies that the current password has expired and cannot be used for login actions.
    MUST_CHANGE_PASSWORD Specifies that the user's password has been changed by the administrator and must be reset by the user before the next login action.
    PASSWORD_LOCKED_OUT Specifies that a password is temporarily locked out as a result of too many invalid login attempts. It cannot be used for login actions.
    EXTERNAL Specifies that a password is managed in a remote directory, not in PingOne. If the referenced gateway in password.gateway does not allow password changes (allowPasswordChanges=false), then password changes are blocked and links for password.forgot and password.reset are not included.

    Password Check

    Password Force Change

    Password Recover

    Password Resend Recovery Code

    Password Unlock

    Read Password State

    Update Password (Self)

    Update Password (Admin)

    Update Password (Set)

    Update Password (Set Value)

    Update Password (LDAP Gateway)

    User Role Assignments

    The users role assignments endpoint implements functions to create, read, and delete the role assignments associated with user resources. For more information about roles and the permissions associated with each role, see Roles.

    Role assignments are defined by the role itself, and at a more granular level by the scope attribute associated with the role assignment. The role assignment scope identifies the type of platform resource that defines the scope, and the id of the specific resource to which the scope applies. The following sample shows the scope attribute, which includes the resource type and id attributes. In this case, the scope is restricted to the environment resource identified by its id.

    {
  "scope": {
   "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
   "type": "ENVIRONMENT"
   }
}

    Role assignment scopes can be:

    • Organization

    • Environment

    • Population

    • Application

    Users role assignments data model
    Property Type Required? Mutable? Description
    environment.id String N/A Read-only The environment associated with the user.
    id String N/A Read-only Specifies the user role assignment ID.
    readOnly Boolean Optional Mutable Specifies whether this role assignment can be deleted by the current actor.
    role.id String Required Mutable The role ID.
    scope.id String Required Mutable The role assignment scope ID. When this is an application ID, because an application ID is guarenteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.
    scope.type String Required Mutable The type of resource defining the scope of the Role assignment. Options are ORGANIZATION, ENVIRONMENT, and POPULATION, APPLICATION.
    Use Cases
    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.
    404 The requested resource was not found.

    Create User Role Assignment

    Read Role Assignments

    Read One Role Assignment

    Delete User's Role Assignment

    User Application Role Assignments

    The users application role assignments endpoint implements functions to create, read, and delete the PingOne Authorize application role assignments associated with user resources. For more information about application roles and the permissions associated with each role, see PingOne Authorize Application Resources and Roles.

    Users role assignments data model
    Property Type Required? Mutable? Description
    environment.id String N/A Read only Specifies the environment associated with the user.
    id String Required Mutable Specifies the application role ID to assign to the specified user.
    name String N/A Read only Specifies the name of the application role assigned to the user.
    description String N/A Read only Specifies the description of the application role assigned to the user.
    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.
    404 The requested resource was not found.

    Create User Application Role Assignment

    Read User Application Role Assignments

    Delete User Application Role Assignment

    User Agreement Consents

    A user agreement consent resource is a record of a user consenting to a terms of service agreement for a specific language and revision. Only the latest consent record is available through a GET request, which shows only the current agreement consent state for (1) all the user's agreement consents, or (2) the current agreement consent state for one specific agreement.

    This service provides operations to read and update user agreement consent resources.

    You need the Environment Admin role to perform operations on user consent resources.

    Agreement consent state data model

    The properties described here identify the agreement consents associated with a specified user and current state of the agreement consent (represented by the lastConsent properties).

    Property Type Required? Mutable? Description
    agreement Object Required Mutable Specifies the agreement resource for this agreement consent.
    agreement.id String Required Mutable Specifies the UUID of the agreement resource for this agreement consent.
    language Object Required Mutable Specifies the language resource associated with this agreement consent.
    language.id String Required Mutable Specifies the language resource UUID associated with this agreement consent. If the status is ACCEPTED, then this is the language associated with the consent. For any other status value, this represents the language to which the user must consent.
    lastConsent.at DateTime N/A Read-only Specifies the date and time at which the user consented to the agreement.
    lastConsent.expiresAt DateTime N/A Read-only Specifies the date and time at which the user consent to the agreement expires.
    lastConsent.language Object N/A Read-only Specifies the language resource associated with the user's last agreement consent.
    lastConsent.language.id String N/A Read-only Specifies the language resource UUID associated with the user's last agreement consent.
    lastConsent.revision Object N/A Read-only Specifies the revision resource associated with the user's last agreement consent.
    lastConsent.revision.id String N/A Read-only Specifies the revision resource UUID associated with the user's last agreement consent.
    revision Object Required Mutable Specifies the revision resource associated with this agreement consent.
    revision.id String Required Mutable Specifies the revision resource UUID associated with this agreement consent.
    status String N/A Read-only Specifies whether the consent is valid or not, depending on the agreement, language, and revision configuration. Options are PENDING, ACCEPTED, REVOKED, EXPIRED, and AGREEMENT_DISABLED. This property value is computed dynamically when the resource is returned.
    user Object Required Mutable Specifies the user associated with this agreement consent.
    user.id String Required Mutable Specifies the UUID of the user associated with this agreement consent.
    User consent event model

    The properties described here are used with the PingOne audit reporting service to search for a user's consent history for specific agreements. For more information about the audit events to use to query a user's consent history, see Agreement Management.

    Property Type Required? Mutable? Description
    consentedAt DateTime Optional Mutable Specifies the date and time at which the user consented to the agreement.
    agreement Object Required Mutable Specifies the agreement resource for this agreement consent.
    agreement.id String Required Mutable Specifies the UUID of the agreement resource for this agreement consent.
    language Object Required Mutable Specifies the language resource associated with this agreement consent.
    language.id String Required Mutable Specifies the language resource UUID associated with this agreement consent.
    revision Object Required Mutable Specifies the revision resource associated with this agreement consent.
    revision.id String Required Mutable Specifies the revision resource UUID associated with this agreement consent.
    status String N/A Read-only Specifies whether the consent is valid or not, depending on the agreement, language, and revision configuration. Options are ACTIVE, INVALID, and EXPIRED. This property value is computed dynamically when the resource is returned.
    user Object Required Mutable Specifies the user associated with this agreement consent.
    user.id String Required Mutable Specifies the UUID of the user associated with this agreement consent.
    Response codes
    Code Message
    200 Successful operation.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Accept Agreement

    Revoke Agreement

    Read All User Agreement Consents

    Read One User Agreement Consent

    User OAuth Scope Consents

    A user OAuth scope consent resource is a record of a user's OpenID Connect OAuth scope consents. The OAuth scope consent service gives end users the ability to control the user data they wish to share with third party applications. These consents granted through PingOne help enterprises build trust with customers who want to use third-party applications with the enterprise's service but want control over the data they are agreeing to share.

    This service provides operations to create, read, and update user OAuth scope consent resources. This service applies only to applications that have their protocol property set to OPENID_CONNECT.

    You need the Identity Data Admin role to perform operations on user oauth scope consent resources.

    Expanding and filtering response data

    You can expand GET {{apiPath}}/environments/{{envID}}/users{{userID}}/oauthConsents and GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/oauthConsents/{{oauthConsentID}} results with the expand=applications query parameter to return additional information about the associated application in the response.

    You can filter a user's consents by application ID or by application name using the query parameters filter=application.id eq "{{appId}}" or filter=application.name eq "{{appName}}" on GET operations.

    Property Type Required? Mutable? Description
    application Relationship Optional Mutable A relationship that specifies the application associated with this OAuth scope consent.
    application.id String Optional Mutable A string that specifies the ID of the application associated with this OAuth scope consent. This property is required for applications with an application.appType property of PINGONE.
    application.name String Optional Mutable A string that specifies the name of the application associated with this OAuth scope consent. This property is required for applications with an application.appType property of EXTERNAL.
    application.appType String Optional Mutable A string that specifies the application type associated with this OAuth scope consent. Options are PINGONE and EXTERNAL.
    browser UserAgentInfo Optional Read only Information that specifies the browser used to make the consent. The UserAgentInfo object includes data for name (required) and version.
    consentedAt Date Optional Read only The time when a user consent occurs.
    device UserAgentInfo Optional Read only Information that specifies the device used to make the consent. The UserAgentInfo object includes data for the device type.
    environment.id String Optional Read only A string that specifies the ID of the environment associated with this OAuth scope consent.
    operatingSystem UserAgentInfo Optional Read only Information that specifies the operating system of the device used to make the consent. The UserAgentInfo object includes data for name (required) and version.
    scope Set Optional Mutable A set of strings that specifies the scopes associated with this OAuth scope consent.
    status String Required Mutable A string that specifies whether the consent is valid or not. Options are ACCEPTED, REVOKED, and DECLINED.
    user Relationship Optional Mutable A relationship that specifies the user associated with this OAuth scope consent.
    user.id String Optional Mutable A string that specifies the ID of the user associated with this OAuth scope consent.
    updatedAt Date Optional Read only The time when a user consent is updated.
    Response codes
    Code Message
    200 Successful operation.
    201 Created.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Record User OAuth Scope Consent

    Read All User OAuth Scope Consents

    Read One User OAuth Scope Consent

    Revoke User OAuth Scope Consent

    User Accounts

    The user account management endpoint provides functionality to unlock a user account. For information about how to configure account lockout for MFA actions, see MFA Settings.

    Account state data model

    Property Type Required? Mutable? Description
    account.canAuthenticate Boolean Required Mutable Indicates whether the user can authenticate. If the value is set to false, the account is locked or the user is disabled, and unless specified otherwise by the administrative configuration, the user will be unable to authenticate.
    account.lockedAt Date N/A Read-only The date-time the specified user account was locked. This property might be absent if the account is unlocked or if the account was locked out automatically by failed password attempts.
    account.secondsUntilUnlock Integer Optional Read-only The number of seconds until the user's account is unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).
    account.status String Required Mutable The account locked state. Options are LOCKED and OK.
    account.unlockAt Date Optional Mutable The time the specified user account will be unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).

    User Account Unlock

    User Account Lock

    User Sessions

    Represents the user session associated with a flow. You can read all sessions, read a single session, or delete a single session associated with your user ID. Administrators can read all sessions for a specified user, read a single session for a specified user, or delete a user's session for the environment or population for which they have administrator privileges.

    See also Sessions for interfaces on the Environment endpoint.

    User session data model

    Property Type Required? Mutable? Description
    activeAt Date N/A Read-only The last user activity time on this session (such as, completing a flow, or an application activity like validating a token).
    browser.name String N/A Read-only The name of the browser.
    browser.version String N/A Read-only The version of the browser.
    createdAt Date N/A Read-only The time the resource was created.
    device.type String N/A Read-only The type of remote device.
    environment.id String Required Immutable The UUID for the environment.
    id String Required Immutable The UUID for the user session.
    lastSignOn.at String N/A Read-only The last time the user signed on using one or more authenticators.
    lastSignOn.remoteIp String N/A Read-only The IP address of the remote device used during the last sign-on.
    locations Object[ ] N/A Read-only Contains the attributes identifying the user location. Only the last 5 locations are maintained.
    location.at Date N/A Read-only The last time the user signed on.
    location.remoteIp String N/A Read-only The IP address of the remote device used during the last sign-on.
    location.city String N/A Read-only The city resolved from the IP address.
    location.state String N/A Read-only The state resolved from the IP address.
    location.region String N/A Read-only The region resolved from the IP address.
    location.country String N/A Read-only The country resolved from the IP address.
    operatingSystem.name String N/A Read-only The name of the operating system.
    operatingSystem.version String N/A Read-only The operating system version.
    user.id String Required Immutable The UUID for the user.

    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.

    Read All Sessions

    Read One Session

    Delete Session

    User Email Verification

    The user email verification endpoint supports operations to verify a user's email through a verification code.

    User email verification data model
    Property Type Required? Mutable? Description
    environment.id String N/A Read-only The environment associated with the user.
    user.id String N/A Read-only The user ID.
    notificationType String Required Mutable Indicates whether the notification is sent to an admin or user.
    verificationCode String Required Read-only The code sent to verify the user's email. The email verification code is 8 alphanumeric characters with a timeout of 24 hours. These attributes are not configurable.

    For more user property descriptions, see the Users data model.

    Send Email Verification (Code)

    Verify Email (Code)

    User Admin Invitations

    The users endpoint supports operations to send administrator invitations to users.

    User invitations data model

    Property Type Required? Mutable? Description
    invite.acceptUrl String Optional Mutable The URL where the invited user can accept the invitation.
    invite.expirationMinutes String Optional Mutable How long the invite is valid for, represented in minutes.
    invite.isAdmin Boolean Required Mutable Indicates if the invitation is an admin invitation.

    For more user property descriptions, see the Users data model.

    Response codes
    Code Message
    200 Successful operation.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Send Admin Invite

    Resend Admin Invite

    Metrics

    PingOne metrics provide information about platform activities. The following services give you access to platform data:

    • Activities

      Audit reporting caches incoming audit messages and provides information about audit events for a specified date range. User activities track and aggregate user-activity information on user sign-on attempts and total active user counts.

      For more information, see Audit Activities and User Activities.

    • Identity accounts

      Active identity counts use authentication and password-evaluation user events to determine whether an identity is active within a specified sampling period. Total identity counts provide the number of unique identities associated with a specified environment per day.

      For more information, see Active identity counts, Authentication per Application, and Total identities.

    • Subscriptions

      The subscription service provides an interface for third-party auditing tools to subscribe to and consume PingOne audit activity events. The service listens for translated audit activities as the source of events and transmits messages about these events to the subscribing audit application.

      For more information, see Subscriptions.

    Active Identity Counts

    Active identity counts gather information about identities that have completed one of the following actions successfully during a specified period of time:

    • Authentication

      The identity has completed at least one authentication flow successfully.

    • Password check

      The identity has completed at least one password check successfully.

    This service uses authentication and password-evaluation user events to determine whether an identity is active within a specified sampling period.

    Read Active Identity Counts

    Read Active Identity Counts by Date Range

    Read Active Identity Counts by License

    Audit Activities

    Audit reporting caches incoming audit messages and provides endpoints to request audit events for a specified date range. The /activities endpoint returns all audit log events over the specified period of time. The response shows complete audit entries, and it pages the returned data if the number of entries requires multiple pages.

    The following events and actors are tracked:

    • Actions

      Logs any action or activity against a defined PingOne resource. The audit message includes the ID for the resource affected by the event.

    • Actors

      Tracks the actor or agent who initiated the action. The audit message includes the unique identifier and the friendly name of the actor (end user) responsible for the event and the client used by the actor to perform the action on the resource.

    • Date and time

      The date and time the audit activity was recorded.

    • Status

      Tracks and caches the resulting status of the action. The audit message specifies the success or failure of the event, and if a failure occurred, it provides the reason for the failure.

    Audit reporting data model

    Property Description
    action.description A string that specifies the description of the action performed.
    action.type A string that specifies the type of action performed (such as authentication or password reset).
    actors.client.id A string that specifies the ID of the client.
    actors.client.name A string that specifies the name assigned to the client for PingOne sign on.
    actors.client.type A string that specifies the type of actor. Options are USER or CLIENT.
    actors.client.href A string that specifies the URL for the specified client resource.
    actors.client.environment.id A string that specifies the ID of the environment resource associated with the client.
    actors.user.id A string that specifies the ID of the user.
    actors.user.name A string that specifies the name assigned to the user for PingOne sign on.
    actors.user.href A string that specifies the URL for the specified user resource.
    actors.user.type A string that specifies the type of actor. Options are USER or CLIENT.
    actors.user.environment.id A string that specifies the ID of the environment resource associated with the user.
    actors.user.population.id A string that specifies the ID of the population resource associated with the user.
    correlationId A string that specifies a PingOne identifier for multiple messages in a transaction.
    createdAt The date and time at which the event was created (ISO 8601 format).
    id A string that specifies the ID of the audit activity event.
    internalCorrelation.sessionId A string that specifies the PingOne actor session ID.
    internalCorrelation.transactionId A string that specifies the PingOne transaction ID.
    recordedAt The date and time at which the event was recorded (ISO 8601 format).
    resources.href A string that specifies the URL for the specified resource.
    resources.id A string that specifies the ID assigned as the key for the identifier resource (such as the environment, population or event message).
    resources.name A string that can be either the user name or the name of the environment, based on the resource type.
    resources.type A string that specifies the type of resource associated with the event. Options are USER, ORGANIZATION, or ENVIRONMENT.
    resources.population.id The UUID assigned as the key for the population resource.
    result.description A string that specifies the description of the result of the operation.
    result.id A string that specifies the ID for the result of the operation.
    result.status A string that specifies the result of the operation. Options are succeeded or failed.
    source.ipAddress The IP address of the originating HTTP request.
    source.userAgent The User-Agent header value of the originating HTTP request.
    tags.adminIdentityEvent A string identifying the activity as the action of an administrator on other administrators.

    Filtering data

    The GET {{apiPath}}/environments/{{envID}}/activities and POST {{apiPath}}/environments/{{envID}}/activities requests accept SCIM filtering expressions to fine-tune the response data. For large collections, additional filtering expressions can be added to the request URL to focus on particular event types.

    The minimum filter must include:

    • A date range for the recorded event time.
    Filter Description
    recordedat lt "yyyy-MM-dd'T'HH:mm:ss.SSSZ" Audit events recorded before the specified time.
    recordedat gt "yyyy-MM-dd'T'HH:mm:ss.SSSZ" Audit events recorded after the specified time.

    For example, this SCIM filter returns audit events from the start date of "2018-01-01" and an end date of "2018-03-31":

    https://api.pingone.com/v1/environments/{{envID}}/activities?filter=recordedat gt "2018-01-01T00:00:00Z" AND recordedat lt "2018-03-31T23:59:00Z"

    The filter can also include any one of the following:

    • Population ID
    • Actor ID and optional population ID.
    • Action Type and optional population ID
    • Resource ID
    • Resource Type and optional population ID
    Filter Description
    resources.population.id eq ":id" Audit events associated with the specified population.
    actors.user.id eq ":id" Audit events performed by the specified user ID or client ID. Optionally, you can include the associated population.
    action.type Audit events recorded for the specified type of action (such as, authentication, password reset). Optionally, you can include the associated population.
    resources.id eq ":id" Audit events recorded for the specified resource.
    resources.type Audit events recorded for the specified type of resource. This can be any one of the following: ALL, USER, ENVIRONMENT, ORGANIZATION. Optionally, you can include the associated population.
    tags Audit events for the adminIdentityEvent tag. Currently, the adminIdentityEvent tag is the only one supported.

    These SCIM operators can be applied to the following attributes:

    • eq (equals)

      Supported attributes: correlationid, actors.user.id, actors.user.name, actors.client.id, action.type, resources.id, resources.type, resources.population.id, org.id, environment.id

    • gt (greater than)

      Supported attributes: recordedat

    • lt (less than)

      Supported attributes: recordedat

    • ge (greater than or equal to)

      Supported attributes: recordedat

    • le (less than or equal to)

      Supported attributes: recordedat

    • and (logical AND)

      Logical AND for building compound expressions in which both expressions are true.

    • or (logical OR)

      Logical OR for building compound expressions if either expression is true.

    For more information about SCIM syntax and operators, see Conventions.

    Response codes

    Code Message
    200 Successful operation.
    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.

    Read Audit Activities

    Read Audit Activities

    Read One Audit Activity

    Authentications per Application

    The authentications per application service calculates the number of successful sign-on actions for all applications in a specified environment during a specified time period. This metric shows how often applications are accessed, using authentications as the measure of the application's usage. Organizations can use this metric to:

    • Determine which applications are responsible for the highest volume of authentication requests, in rank order.

    • See which applications are rarely used and are candidates for decommission.

    • See the relative number of authentication requests for each connected application.

    • Determine whether an application's usage is growing or shrinking over time.

    • View the total number of authentication requests per application over time.

    The count of successful authentications is the total number of FLOW.UPDATED events with COMPLETED status during the specified period.

    For example, suppose you want to see the number of authentications (per application) per day for a three-day period starting on September 1, 2019. Requests to this service require the following filter parameter to define the query:

    • occurredAt

      Specifies the start date for the period of interest. For this example, to specify a date range starting on September 1, 2019, the value is occurredAt ge "2019-09-01T00:00:00Z".

    Requests to this service also require the following query parameters to define the query:

    • samplePeriod

      Specifies the time interval in hours. For this example, to specify a daily interval, the value is samplePeriod=24.

    • samplePeriodCount

      Specifies the number of sample periods. For this example, to specify three days of results, the value is samplePeriodCount=3.

    The authentications per application service supports limit as an optional query parameter to specify a subset of applications returned in the response. For information about limiting collections, see Conventions.

    Authentications per application data model

    Property Type Required? Mutable? Description
    endDate Date Required Mutable The date and time the authentication data collection ends (ISO 8601 format).
    partial Boolean Optional Mutable Indicates the partial period. When visible in the response data and set to true, this indicates that the response represents a shorter duration than requested through the samplePeriod parameter.
    signons Integer Required Mutable The number of authentications for the application identified by its application ID between the start and end dates of the sample period.
    startDate Date Required Mutable The date and time the authentication data collection starts (ISO 8601 format).

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Internal server error.

    Read Authentications Per Application

    Read Authentications Per Application (Partial)

    Subscriptions (webhooks)

    The subscription service provides an interface for third-party auditing tools to subscribe to and consume PingOne audit activity events. The service listens for translated audit activities as the source of events and transmits messages about these events to the subscribing audit application.

    Use only IPv4 addresses for webhooks. IPv6 addresses are not fully-supported.

    For more information about subscriptions (webhooks), see Webhooks in the PingOne Admin Guide.

    Subscriptions data model

    Property Type Require? Mutable? Description
    createdAt Date N/A Read-only The date and time at which the subscription resource was created (ISO 8601 format).
    enabled Boolean Required Mutable Indicates whether a created or updated subscription should be active or suspended. A suspended state ("enabled":false) accumulates all matched events, but these events are not delivered until the subscription becomes active again ("enabled":true). For suspended subscriptions, events accumulate for a maximum of two weeks. Events older than two weeks are deleted. Restarted subscriptions receive the saved events (up to two weeks from the restart date).
    environment.id String Required Immutable The environment resource’s unique identifier associated with the subscription.
    filterOptions.includedActionTypes String[] Required Mutable A non-empty array that specifies the list of audit events that should be matched for the subscription. See Audit Reporting Events for valid audit events.
    filterOptions.includedApplications String[] Optional Mutable The list of applications (by ID) whose events are monitored by the subscription (maximum of 10 IDs in the array). If a list of applications is not provided, events are monitored for all applications in the environment.
    filterOptions.includedPopulations String[] Optional Mutable The list of populations (by ID) whose events are monitored by the subscription (maximum of 10 IDs in the array). This property matches events for users in the specified populations, as opposed to events generated in which the user in one of the populations is the actor.
    filterOptions.includedTags String[] Optional Mutable The tags that events must have to be monitored by the subscription. If tags are not specified, all events are monitored. Currently, the available tags are:
    • adminIdentityEvent. Identifies the event as the action of an administrator on other administrators.
    filterOptions.ipAddressExposed Boolean Optional Mutable Whether the IP address of an actor should be present in the source section of the event.
    filterOptions.userAgentExposed Boolean Optional Mutable Whether the User-Agent HTTP header of an event should be present in the source section of the event.
    format String Required Mutable One of the supported subscription formats. Options are ACTIVITY, SPLUNK, and NEWRELIC.
    httpEndpoint.headers String[] Required Mutable The headers applied to the outbound request (for example: "Authorization": "Basic username:password"). The purpose of these headers is for the HTTPS endpoint to authenticate the PingOne service, ensuring that the information from PingOne is from a trusted source.
    httpEndpoint.url String Required Mutable A string that specifies a valid HTTPS URL to which event messages are sent.
    id The resource’s unique identifier.
    name String[] Required Mutable The subscription name.
    tlsClientAuthKeyPair.id String Optional Mutable The ID of a key to be used for outbound mutual TLS (mTLS) authentication. This key is used as a client credential to authenticate the webhook. The key must have a usageType of OUTBOUND_MTLS. See Certificate management for information on creating a key. If this property is set, verifyTlsCertificates must be set to true.
    updatedAt Date N/A Read-only The date and time at which the subscription resource was last updated (ISO 8601 format).
    verifyTlsCertificates Boolean Required Mutable Indicates whether a certificates should be verified. If this property's value is set to false, then all certificates are trusted. (Setting this property's value to false introduces a security risk.) This value must be set to true if tlsClientAuthKeyPair.id is set.

    Subscription Events

    You can subscribe to any of the audit events listed in Audit Reporting Events.

    The audit events triggered by your subscription requests are also in the Audit Report Events list: SUBSCRIPTION.CREATED, SUBSCRIPTION.UPDATED, and SUBSCRIPTION.DELETED.

    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 The request could not be completed. You do not have access to this resource.
    404 The requested resource was not found.

    Create Subscriptions

    Read All Subscriptions

    Read One Subscription

    Update Subscription

    Delete Subscription

    Total Identities

    The total identities service retrieves the count of unique identities associated with a specified environment. The response shows the total number of users, divided into daily (24-hour) reporting periods, from the specified startDate through the endDate. The total identities count tracks the add and delete user operations to determine the changes in total number of unique identities over each 24-hour period. This service uses a SCIM query filter to control the sample size, showing the unique identity counts (on a per day basis) within the specified date range.

    Total identities data model

    Property Type Required? Mutable? Description
    date Date N/A Read-only The date and time the total identities count starts for the sampling period (ISO 8601 format).
    totalIdentities Integer N/A Read-only The total unique identities count for the sampling period.

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Internal server error.

    Read Total Identity Counts

    User Activities

    The User Activities API returns counts for successful and failed sign-on actions as well as a count for password resets over a designated period of time. The service uses stream processors that listen to users and login_attempts events. These events are collected and presented by time period. The service supports the SCIM startDate, endDate, and sampleSize query filtering parameters to request user-activity information for a specific date range and sample size.

    User activities data model

    Property Type Required? Mutable? Description
    startDate Date N/A Read-only The start date for the activity period.
    endDate Date N/A Read-only The end date for the activity period.
    environment.id String N/A Read-only The environment resource’s unique identifier.
    userSignOns.successes Integer N/A Read-only The total number of successful user sign ons for the activity period.
    userSignOns.failures Integer N/A Read-only The total number of failed user sign ons for the activity period.
    passwordResets Integer N/A Read-only The total number of password resets for the activity period.

    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.
    404 The requested resource was not found.

    Read User Activities

    PingOne DaVinci

    PingOne DaVinci is an orchestration platform that helps you design and create flows. Flows are constructed, logical paths that can contain both user-facing and backend elements.

    DaVinci enables you to visualize the entire flow process. By controlling integrations and connections across multiple applications and identity ecosystems in a single platform, you can manage and troubleshoot complex user experiences such as sign-on and registration. The DaVinci APIs specifically guide users through these kinds of authorization and authentication tasks.

    After you create a flow, you can associate the flow with a flow policy, and associate the flow policy with an application to make the flow available to the application's users.

    DaVinci flows with PingOne applications

    The following workflow outlines the interaction between PingOne applications and DaVinci flows and flow policies.

    1. PingOne applications support a configuration option to assign DaVinci flow policies to the application. For information about creating DaVinci flows and flow policies, see Getting Started with DaVinci. For information on designating a DaVinci flow policy as a PingOne flow, see Configuring a flow policy.

    2. To initiate the flow, call the /{{envID}}/as/authorize endpoint. (The supported grant types are authorization_code and implicit.)

    3. The PingOne authorization service retrieves the application configuration data. Based on the configuration, the application can use either a PingOne sign-on policy or a DaVinci flow policy to determine the sign-on workflow. To assign DaVinci flow policies to applications, see Application Flow Policy Assignments.

    4. For DaVinci flow policy use cases, the PingOne protocol service renders the sign-on flow page using a DaVinci widget. For more information about DaVinci widgets, see Launching a flow with the widget in the PingOne admin documentation.

    5. The DaVinci widget manages the flow, and after the flow completes, the PingOne SSO Connector creates a session and passes control back to the protocol service to create an authorization response and send it to the application.

    6. The application continues its normal flow, calling the PingOne token endpoint to obtain the tokens.

    Use Cases

    PingOne regional domains

    See PingOne API domains in Working with PingOne APIs for the regional domains supported for DaVinci (and all other PingOne services).

    DaVinci Admin APIs

    The PingOne DaVinci Admin APIs provide access to DaVinci operations through the PingOne API resource server. These services are called using the api.pingone.com domain (or api.pingone.ca, api.pingone.eu, api.pingone.asia, and api.pingone.com.au for other geographic regions) to manage DaVinci workflow configuration.

    At this time, the following services are supported on the PingOne API resource server:

    DaVinci Admin Variables

    PingOne DaVinci Admin Variables service provides endpoints to create, read, update, and delete DaVinci variables. Variables are values that can be read and modified during a flow. Every variable has a context, which determines how widely its value is shared.

    The options for the variable's context types are:

    • flow

      The variable is tied to a specific flow and has a single, persistent value until that value is changed.

    • flowInstance

      The variable can be used in multiple flows.

      • If the variable's value is set within a flow, the variable instance in that flow gets the value set by the flow's execution.

      • If the variable's value is not set within a flow, the variable instance in that flow inherits the value.

    • user

      The variable has a separate value for each user. If you use a variable with this context in a flow, the user must be identified.

    • company

      The variable has a single value for the company. This value is used in all flows and for all users.

    DaVinci Admin variable data model properties

    Property Type? Required? Mutable? Description
    createdAt Date N/A Read only The time when the variable was created.
    context String Required Immutable The context or type of the variable. Options are flow, flowInstance, user, or company.
    dataType String Required Mutable Data type of the variable. Can be STRING, BOOLEAN, NUMBER, or OBJECT.
    displayName String Optional Mutable A human-readable variable name set in the request.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    flowId String Immutable Optional The flow ID of the DaVinci flow associated with the variable.
    id String N/A Read only The variable ID.
    max Integer Optional Mutable The maximum value of the variable.
    min Integer Optional Mutable The minimum value of the variable.
    mutable Boolean Optional Mutable Specifies whether the variable is mutable, which allows nodes within a flow to change the value of the variable. If the value property is null, this property is required.
    name String Required Mutable The variable name.
    updatedAt Date N/A Read only The time when the variable was modified.
    value String/Number/Boolean/Object Optional Mutable An internally stored value that is part of a HashMap/Object. If the mutable property is set to false, this property is required. If mutable is not set on the request, it defaults to true.

    Limiting and filtering data

    These SCIM operators can be applied to the following attributes:

    • eq (equals)

      Supports attributes of type STRING and BOOLEAN.

    • sw (starts with)

      Supports attributes of type STRING.

    • ew (ends with)

      Supports attributes of type STRING.

    • co (contains)

      Supports attributes of type STRING.

    • and (logical AND)

      Logical AND for building compound expressions in which both expressions are true.

    • or (logical OR)

      Logical OR for building compound expressions if either expression is true.

    For information about paging and ordering the response for Read All DaVinci Variables, see Paging, ordering, and filtering collections.

    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.

    Create DaVinci Variable

    Read All DaVinci Variables

    Read One DaVinci Variable

    Update DaVinci Variable

    Delete DaVinci Variable

    DaVinci Admin Connectors

    PingOne DaVinci Admin Connector service provides endpoints to read DaVinci connector resources. Connectors give DaVinci the ability to integrate third party technologies, HTML pages, and other tools to create a sign-on flow. They define the capabilities that you can use as nodes in a flow. For example, an HTTP connector provides the capability to present an HTML form to collect and submit user information or make REST API calls.

    DaVinci admin connector data model properties

    Property Type? Required? Mutable? Description
    description String Optional Mutable The connector description.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    id String N/A Read only The connector ID (for example, httpConnector).
    metadata Object N/A Read only Represents the metadata information about the connector, such as type, color, and logo.
    metadata.type String N/A Read only The type of connector. Options are core, ping, or service.
    metadata.vendor String N/A Read only The ID of a vendor (for example,microsoft or amazon).
    metadata.colors Object N/A Read only An object that specifies the colors on the canvas.
    metadata.colors.canvas String N/A Read only A hexadecimal representation of the canvas color.
    metadata.colors.canvasText String N/A Read only A hexadecimal representation of the canvas text color.
    metadata.colors.dark String N/A Read only A hexadecimal representation of the shade of darkness.
    metadata.logos String N/A Read only The image name of the connector logo file.
    metadata.logos.canvas Object N/A Read only An object that specifies the canvas.
    metadata.logos.imageFileName String N/A Read only The name of the connector logo image.
    name String Required Mutable The connector name (for example, HTTP).
    version String N/A Read only The version number of the connector.

    DaVinci admin connectors details data model properties

    Property Type? Required? Mutable? Description
    accountConfigView Object[] Optional Mutable Represents the account configuration of the connector. For details, see Core connectors.
    accountConfigView.componentViewSize String Optional Mutable The size of the configuration window.
    accountConfigView.items Array Optional Mutable An array of configurable properties.
    accountConfigView.items.propertyName String Optional Mutable The name of the configurable property.
    accountConfigView.items.items Array Optional Mutable An array of sub-property names under the top level property.
    accountConfigView.items.items.propertyName Array Optional Mutable The name of the sub-property under the top level property.
    capabilities Object[] Optional Mutable A list of all connector capabilities and their input properties. For more information, see Core connectors.
    createdAt Date N/A Read only The time when the connector was created.
    credentialsView Object Optional Mutable Represents the credentials view of the connector.
    credentialsView Object Optional Mutable The fields that will be part of the connector configuration specific to credentials.
    credentialsView.items Array Optional Mutable An array of configurable properties.
    credentialsView.items.propertyName String Optional Mutable The name of the property.
    flowSections Object[] Optional Mutable Represents the flow section to which the connector can be categorized.
    flowSections.name String Optional Mutable The name of the section being shown.
    flowSections.value String Optional Mutable A pointer to the flow section name referenced by other sections in the manifest.
    properties Object Optional Mutable A list of properties that will be used by the capabilities. For more information, see Core connectors.
    sections Object[] Optional Mutable An array of sections shown in Connector Configuration. For more information, see Core connectors.
    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.

    Read All DaVinci Connectors

    Read One DaVinci Connector

    Read DaVinci Connector Details

    DaVinci Admin Connector Instances

    PingOne DaVinci Admin Connector Instances service provides endpoints to create, read, update, and delete DaVinci connector instances. A DaVinci connector instance is one instance of a DaVinci connector (the connection configuration specifies a connector by name). You can then use the capabilities provided by the connector inside a flow, and launch the flow through an application.

    This service also includes an action to clone connector instance resources.

    DaVinci admin connector instances data model properties

    Property Type? Required? Mutable? Description
    connector Object Required Immutable The connector object.
    connector.id String Required Immutable The connector object name (for example, httpConnector).
    createdAt Date N/A Read only The time when the connection was created.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    id String N/A Read only The connector instance resource ID.
    name String Required Mutable The connector instance name.
    properties Object Optional Mutable The configuration of the connector object. This field is not applicable to all connectors and is omitted in the output if empty or null. If the specified connector requires configuration, see the Connector configuration section of the connector documentation for the connector specified in connector.id.
    updatedAt Date N/A Read only The time when the connector instance was updated.
    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.

    Create DaVinci Connector Instance

    Clone DaVinci Connector Instance

    Read All DaVinci Connector Instances

    Read One DaVinci Connector Instance

    Update DaVinci Connector Instance

    Delete DaVinci Connector Instance

    DaVinci Admin Flows

    DaVinci flows are constructed, logical paths that specify the workflow for the user's authorization and authentication experiences.

    Flows consist of one or more nodes joined together. Each node performs a specific task, using one of the capabilities of your connectors. After completing the task, the flow determines which task to perform next until the flow is complete.

    The PingOne DaVinci Admin Flows service provides endpoints to create, read, update, and delete DaVinci flows. This service also includes endpoints to enable, deploy, import, and clone flows.

    DaVinci admin flow data model properties

    Property Type? Required? Mutable? Description
    color String Optional Mutable The color of the flow.
    connectors Array[object] Optional Mutable An array of connectors that apply to the flow. An optional query parameter can toggle behavior, either the names of the connectors are returned or the connection objects themselves are returned as embedded objects.
    connectors.id String Optional Mutable The connector ID (or IDs) associated with the flow. Example connectors are httpConnector, functionsConnector, pingOneVerifyConnector, and annotationConnector.
    createdAt Time N/A Read only The timestamp when the flow was created.
    currentVersion Integer Optional Immutable The saved version of the flow.
    deployedAt Time N/A Read only The stamp when the flow was last deployed.
    description String Optional Mutable The description of the flow.
    enabled Boolean Optional Immutable The state of the flow. This can be stored as its own value in the database or it can reflect an existing flowStatus.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    graphData Object Optional Mutable The graph-based representation of the flow depicted in the UI.
    id String N/A Read only The flow ID.
    inputSchema Array[object] Optional Mutable The flow input parameters in an array of JSONschema objects. If the trigger.type property is AUTHENTICATION, then the flow is a PingOne flow, and the input schema properties are listed in this table. If the trigger.type property is not AUTHENTICATION, then the flow is not a PingOne flow and the input schema properties are described in Input schema for non-PingOne flows data model properties.
    inputSchema.propertyName String Required Mutable If inputSchema is set, the input schema property name is a required property.
    inputSchema.description String Optional Mutable The description for an input schema property.
    inputSchema.isExpanded Boolean Optional Mutable Specifies whether the input schema is expanded in the response.
    inputSchema.preferredDataType String Required Mutable If inputSchema is set, the data type of the input schema property is required. Options are string, number, integer, boolean, array, and object.
    inputSchema.preferredControlType String Optional Mutable The control type of the input schema property. Options are textField.
    inputSchema.required Boolean Optional Mutable Specifies whether the input schema property is required for the flow.
    name String Required Mutable The name of the flow.
    outputSchema Object Optional Mutable The JSONschema output object of the flow.
    outputSchema.output Object Optional Mutable The output object of the output schema.
    outputSchema.output.type String Optional Mutable The output type.
    outputSchema.output.additionalProperties Boolean Optional Mutable Specifies whether the output has additional properties.
    outputSchema.output.properties Object Optional Mutable A JSON object that specifies the output schema's properties.
    outputSchema.output.properties.{{propName}} Object Optional Mutable An output schema property definition.
    outputSchema.output.properties.{{propName}}.type Object Optional Mutable An output schema property's data type.
    publishedVersion Integer Optional Immutable The currently deployed version of the flow.
    settings Object Optional Mutable Flow settings saved by the user. See the Settings property data model table for details.
    trigger Object Optional Mutable The flow trigger object.
    trigger.type String Optional Mutable If the trigger type is set to AUTHENTICATION, you invoke the flow through PingOne OpenID Connect or SAML endpoints. The AUTHENTICATION trigger type overwrites the inputSchema values with the default authentication schema.
    trigger.configuration Object Optional Mutable The configuration object for session reuse.
    trigger.configuration.pwd Object Optional Mutable The configuration object for password session reuse.
    trigger.configuration.pwd.enabled Boolean Optional Mutable Specifies whether this configuration must be used to check for existing sessions.
    trigger.configuration.pwd.lastSignOn Integer Optional Mutable An integer that specifies the duration (in seconds) that an active session can be reused.
    trigger.configuration.mfa Object Optional Mutable The configuration object for MFA session reuse.
    trigger.configuration.mfa.enabled Boolean Optional Mutable Specifies whether this configuration must be used to check for existing sessions.
    trigger.configuration.mfa.lastSignOn Integer Optional Mutable An integer that specifies the duration (in seconds) that an active session can be reused.
    updatedAt Date N/A Read only The timestamp when the flow was updated or saved.
    Settings property data model

    The following table lists the supported flow settings properties that can be used in the settings property.

    Property Type? Required? Mutable? Description
    csp String Optional Mutable Content Security Policy content to which a Content-Security-Policy meta tag will be added. If you use a custom Javascript flow player, it is required.
    css String Optional Mutable The CSS styling rules to be applied to the flow version.
    cssLinks Array Optional Mutable A list of URL locations of CSS files to apply to the flow version.
    customErrorScreenBrandLogoUrl String Optional Mutable The URL of the logo to use for the error page, such as “https://example.com/logo.png".
    customErrorShowFooter Boolean Optional Mutable Show footer in the error screen.
    customFaviconLink String Optional Mutable The URL of the favicon image to use for the page. This image is displayed in the title bar of the browser and in saved bookmarks.
    customLogoUrlSelection String Optional Mutable The URL location of the logo to show on error pages.
    customTitle String Optional Mutable The title of the page. This title is displayed in the title bar of the browser and used for the page title in search engine results.
    doNotSubstituteUnreplacedFields Boolean Optional Mutable By default, unreplaced parameterized fields will be substituted with an empty string. This parameter overrides that behavior if set to true.
    flowHttpTimeoutInSeconds Number Optional Mutable Timeout period for every node's execution time. A response must be returned by a node before this timeout. The default value is 15 seconds. If set to 0, the default timeout value is used.
    flowTimeoutInSeconds Number Optional Mutable The period after which a particular flow execution becomes inactive. The default value is 300 seconds. If set to 0, the default timeout value is used.
    intermediateLoadingScreenCss String Optional Mutable The CSS rules to use for the intermediate page. This setting applies only when the show intermediate page setting is enabled (useIntermediateLoadingScreen).
    intermediateLoadingScreenHtml String Optional Mutable The HTML content of the intermediate page. Applies only when the show intermediate page is enabled (useIntermediateLoadingScreen).
    jsLinks Array Optional Mutable The location of JavaScript files to apply to the flow.
    logLevel String Optional Mutable The log level for flow analytics. Options are None, Info, or Debug.
    pingOneFlow Boolean Optional Mutable PingOne runs this flow for OIDC or SAML authentication. When a flow is invoked, PingOne sends input parameters to be made available for any node in the flow.
    requireAuthenticationToInitiate Boolean Optional Mutable Flow invocation via OpenID requires authentication. Use the /sdktoken endpoint to retrieve the accessToken value, which can be sent in the query parameter &accessToken=<accessToken>.
    scrubSensitiveInfo Boolean Optional Mutable Remove sensitive information from analytics.
    sensitiveInfoFields Array Optional Mutable These fields will be masked with ****** in Flow analytics.
    useCsp Boolean Optional Mutable Enable and add a content security policy if you are adding additional scripts.
    useCustomCss Boolean Optional Mutable When enabled, DaVinci uses the CSS rules in the custom CSS field.
    useCustomScript Boolean Optional Mutable When enabled, DaVinci uses the JavaScript files in the JavaScript files field.
    useIntermediateLoadingScreen Boolean Optional Mutable When enabled, DaVinci shows a custom user-facing page between each node in the flow.
    Input schema for non-PingOne flows data model properties
    Property Type? Required? Mutable? Description
    inputSchema.propertyName String Required Mutable An input schema property name.
    inputSchema.description String Optional Mutable The description for an input schema property.
    inputSchema.isExpanded Boolean Optional Mutable Specifies whether the input schema is expanded in the response.
    inputSchema.preferredDataType String Required Mutable The data type of the input schema property. Options are string, number, integer, boolean, array, and object.
    inputSchema.preferredControlType String Optional Mutable The control type of the input schema property. Options are textField.
    inputSchema.required Boolean Optional Mutable Specifies whether the input schema property is required for the flow.

    Limiting and filtering data

    You can limit the number of results returned on the Read DaVinci Flows and Read One DaVinci Flow requests with the attributes parameter. This parameter filters the response data returned by the request. The query accepts top-level DaVinci admin flow data model properties as a list of comma separated values. The query returns only the specified property values; it removes all other properties from the response. For example, the following request uses the attributes query parameter:

    /environments/{{envID}}/flows/{{davinciFlowID}}?attributes=name,description

    The response returns the following flow data:

    {
   "_links": {...},
   "id": "{{resourceID}}",
   "name": "SomeFlow, 
   "description": "A brief description"
}
    SCIM operators

    These SCIM operators can be applied to the following attributes:

    • eq (equals)

      Supports attributes of type STRING, DATE, NUMBER, and BOOLEAN.

    • gt (greater than)

      Supports attributes of type DATE and NUMBER.

    • ge (greater than or equal to)

      Supports attributes of type DATE and NUMBER.

    • lt (less than)

      Supports attributes of type DATE and NUMBER.

    • le (less than or equal to)

      Supports attributes of type DATE and NUMBER.

    • sw (starts with)

      Supports attributes of type STRING.

    • ew (ends with)

      Supports attributes of type STRING.

    • co (contains)

      Supports attributes of type STRING.

    • within (within a specified date)

      Supports attributes of type DATE.

    • and (logical AND)

      Logical AND for building compound expressions in which both expressions are true.

    • or (logical OR)

      Logical OR for building compound expressions if either expression is true.

    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.

    Create DaVinci Flow

    Deploy a DaVinci Flow

    Clone a DaVinci Flow

    Import DaVinci Flow

    Import DaVinci Legacy Flow

    Read One DaVinci Flow

    Read All DaVinci Flows

    Enable a DaVinci Flow

    Update DaVinci Flow

    Delete DaVinci Flow

    DaVinci Admin Flow Versions

    The PingOne DaVinci Admin Flow Versions service provides endpoints to read, update, and delete DaVinci flow versions. This service also includes endpoints to export, revert, and see details about a flow version.

    DaVinci admin flow versions data model properties

    Property Type? Required? Mutable? Description
    alias String Optional Mutable The user defined flow version alias.
    clonedFrom Number Optional Immutable The version number from which this flow version was cloned or created.
    connectors Array[object] Optional Mutable An array of connectors that apply to the flow.
    connectors[].id String Optional Mutable The connector ID (or IDs) associated with the flow. Example connectors are httpConnector, functionsConnector, pingOneVerifyConnector, and annotationConnector.
    createdAt Time N/A Read only The timestamp when the flow was created.
    deployedAt Time N/A Read only The stamp when the flow was last deployed.
    description String Optional Mutable The description of the flow.
    enabled Boolean Optional Immutable Specifies the state of the flow. This can be stored as its own value in the database or it can reflect an existing flowStatus.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    graphData Object Optional Mutable The graph-based representation of the flow depicted in the UI. See the Flow versions graph data property data model table for details.
    flow Object Required Immutable The flow object associated with this flow version.
    flow.id String Required Immutable The flow ID of the flow associated with this flow version.
    flow.name String Required Immutable The name of the flow associated with this flow version.
    outputSchema Object Required Mutable The JSONschema output object of the flow.
    updatedAt Date N/A Read only The timestamp when the flow was updated or saved.
    version Number Required Mutable The version number of the flow instance represented by this object.
    Flow versions details property data model

    The following table lists the supported flow versions details settings properties.

    Property Type? Required? Mutable? Description
    color String Optional Mutable The color of the flow.
    connectors Array[object] Optional Mutable An array of connectors that apply to the flow.
    connectors.id String Optional Mutable The connector ID (or IDs) associated with the flow.
    description String Optional Mutable The description of the flow.
    enabled Boolean Optional Immutable Specifies the state of the flow.
    graphData Object Optional Mutable The graph-based representation of the flow depicted in the UI. See the Flow versions graph data property data model table for details.
    inputSchema Array[object] Optional Mutable The flow input parameters in an array of JSONschema objects.
    name String Required Mutable The name of the flow.
    outputSchema Object Required Mutable The JSONschema output object of the flow.
    settings Object Optional Mutable Flow settings saved by the user. See the Settings property data model table for details.
    trigger Object Optional Mutable The flow trigger object.
    trigger.type String Optional Mutable If the trigger type is set to AUTHENTICATION, you invoke the flow through PingOne OpenID Connect or SAML endpoints.
    trigger.configuration Object Optional Mutable The configuration object for session reuse.
    trigger.configuration.pwd Object Optional Mutable The configuration object for password session reuse.
    trigger.configuration.pwd.enabled Boolean Optional Mutable Specifies whether this configuration must be used to check for existing sessions.
    trigger.configuration.pwd.lastSignOn Integer Optional Mutable An integer that specifies the duration (in seconds) that an active session can be reused.
    trigger.configuration.mfa Object Optional Mutable The configuration object for MFA session reuse.
    trigger.configuration.mfa.enabled Boolean Optional Mutable Specifies whether this configuration must be used to check for existing sessions.
    trigger.configuration.mfa.lastSignOn Integer Optional Mutable An integer that specifies the duration (in seconds) that an active session can be reused.
    updates Array N/A Read only String of actions taken to generate this version from the previous version.
    Flow versions graph data property data model

    The following table lists the supported flow versions graph data settings properties.

    Property Type? Required? Mutable? Description
    graphData Object Optional Mutable The graph-based representation of the flow depicted in the UI.
    graphData.elements Object Required Mutable If graphData is set, the graphData.elements object must be defined.
    graphData.elements.nodes[] Array[Object] Required Mutable If graphData.elements is set, the graphData.elements.nodes[] object must be defined.
    graphData.elements.nodes[].data Object Required Mutable The node item data associated with the flow version. If graphData.elements.nodes[] is set, the graphData.elements.nodes[]].data object must be defined.
    graphData.elements.nodes[].data.nodeType String Required Mutable The node type associated with the node item.
    graphData.elements.nodes[].data.connectionId String Optional Mutable The connection ID associated with the node item.
    graphData.elements.nodes[].data.connectorId String Optional Mutable The connector ID associated with the node item.
    graphData.elements.nodes[].data.name String Optional Mutable The name of the node item.
    graphData.elements.nodes[].data.label String Optional Mutable The label associated with the node item.
    graphData.elements.nodes[].data.status String Optional Mutable The status of the node item.
    graphData.elements.nodes[].data.capabilityName String Optional Mutable The name of the capability associated with the node item.
    graphData.elements.nodes[].data.type String Optional Mutable The type associated with the node item.
    graphData.elements.nodes[].data.properties Object Optional Mutable The properties associated with the node item.
    graphData.elements.nodes[].data.properties.nodeTitle Object Optional Mutable The node title object.
    graphData.elements.nodes[].data.properties.nodeTitle.value String Required Mutable The node title text.
    graphData.elements.nodes[].data.properties.code Object Optional Mutable The node item code object.
    graphData.elements.nodes[].data.properties.code.value String Required Mutable The code associated with the node item.
    graphData.elements.nodes[].data.properties.type Object Optional Mutable The node type object.
    graphData.elements.nodes[].data.properties.type.value String Required Mutable The node type.
    graphData.elements.nodes[].data.properties.customCSS Object Optional Mutable The node's stylesheet object.
    graphData.elements.nodes[].data.properties.customCSS.value String Required Mutable The node's CSS.
    graphData.elements.nodes[].data.properties.customHTML Object Optional Mutable The node's HTML object.
    graphData.elements.nodes[].data.properties.customHTML.value String Required Mutable The node's custom HTML.
    graphData.elements.nodes[].data.properties.customScript Object Optional Mutable The node's script object.
    graphData.elements.nodes[].data.properties.customScript.value String Required Mutable The node's custom scripts.
    graphData.elements.nodes[].data.properties.backgroundColor Object Optional Mutable The node's background color object.
    graphData.elements.nodes[].data.properties.backgroundColor.value String Required Mutable The node's background color.
    graphData.elements.nodes[].data.properties.inputSchema Object Optional Mutable The node's input schema object.
    graphData.elements.nodes[].data.properties.inputSchema.value String Required Mutable The node's input schema.
    graphData.elements.nodes[].data.properties.outputSchema Object Optional Mutable The node's output schema object.
    graphData.elements.nodes[].data.properties.outputSchema.value String Required Mutable The node's output schema.
    graphData.elements.nodes[].data.properties.message Object Optional Mutable The node's message object.
    graphData.elements.nodes[].data.properties.message.value String Required Mutable The node's message text.
    graphData.elements.nodes[].data.properties.showContinueButton Object Optional Mutable The node's show continue button object.
    graphData.elements.nodes[].data.properties.showContinueButton.value Boolean Required Mutable Specifies whether to show the node's continue text.
    graphData.elements.nodes[].data.properties.saveVariables Object Optional Mutable The node's save variables object.
    graphData.elements.nodes[].data.properties.saveVariables.value Array[Object] Required Mutable An array of variables that are saved.
    graphData.elements.nodes[].data.properties.formFieldList Object Optional Mutable The node's form fields object.
    graphData.elements.nodes[].data.properties.formFieldsList.value Array[Object] Required Mutable An array of form fields associated with the node.
    graphData.elements.nodes[].data.properties.variableInputList Object Optional Mutable The node's variable input list object.
    graphData.elements.nodes[].data.properties.variableInputList.value Array[Object] Required Mutable An array of input variables associated with the node.
    graphData.elements.nodes[].data.properties.additionalProperties Array[Object] Optional Mutable An array of additional properties allowed by the node.
    graphData.elements.nodes[].data.additionalProperties Array[Object] Optional Mutable An array of additional properties allowed in the Item definition.
    graphData.elements.nodes[].position Object Required Mutable The node's position object.
    graphData.elements.nodes[].position.x Number Required Mutable The node's x-axis position.
    graphData.elements.nodes[].position.y Number Required Mutable The node's y-axis position.
    graphData.elements.nodes[].group String Required Mutable The node's group.
    graphData.elements.nodes[].removed Boolean Required Mutable Specifies whether the node can be removed.
    graphData.elements.nodes[].selected Boolean Required Mutable Specifies whether the node can be selected.
    graphData.elements.nodes[].selectable Boolean Required Mutable Specifies whether the node is selectable.
    graphData.elements.nodes[].locked Boolean Required Mutable Specifies whether the node is locked.
    graphData.elements.nodes[].grabbable Boolean Required Mutable Specifies whether the node is grabbable.
    graphData.elements.nodes[].pannable Boolean Required Mutable Specifies whether the node can be moved.
    graphData.elements.nodes[].classes String Optional Mutable The classes associated with the node.
    graphData.elements.edges[] Array[Object] Required Mutable The object that describes the graph data element edges.
    graphData.elements.edges[].data Object Required Mutable The object that describes the edges data.
    graphData.elements.edges[].data.id String Required Mutable The edges element ID.
    graphData.elements.edges[].data.source String Required Mutable The edges element source.
    graphData.elements.edges[].data.target String Required Mutable The edges element target.
    graphData.elements.edges[].position Object Required Mutable The edge's position object.
    graphData.elements.edges[].position.x Number Required Mutable The edge's x-axis position.
    graphData.elements.edges[].position.y Number Required Mutable The edge's y-axis position.
    graphData.elements.edges[].group String Required Mutable The edge's group.
    graphData.elements.edges[].removed Boolean Required Mutable Specifies whether the edge can be removed.
    graphData.elements.edges[].selected Boolean Required Mutable Specifies whether the edge can be selected.
    graphData.elements.edges[].selectable Boolean Required Mutable Specifies whether the node is selectable.
    graphData.elements.edges[].locked Boolean Required Mutable Specifies whether the edge is locked.
    graphData.elements.edges[].grabbable Boolean Required Mutable Specifies whether the edge is grabbable.
    graphData.elements.edges[].pannable Boolean Required Mutable Specifies whether the edge can be moved.
    graphData.elements.edges[].classes String Optional Mutable The classes associated with the item.
    graphData.elements.data String Required Mutable The data associated with the element.
    graphData.elements.zoomingEnabled Boolean Required Mutable Specifies whether zooming is enabled for the element.
    graphData.elements.userZoomingEnabled Boolean Required Mutable Specifies whether user zooming is enabled for the element.
    graphData.elements.zoom Number Required Mutable The zoom number.
    graphData.elements.minZoom Number Required Mutable The minimum zoom number.
    graphData.elements.maxZoom Number Required Mutable The maximum zoom number.
    graphData.elements.panningEnabled Boolean Required Mutable Specifies whether the element can be moved.
    graphData.elements.userPanningEnabled Boolean Required Mutable Specifies whether the element can be moved by the user.
    graphData.elements.pan Object Required Mutable The panning object.
    graphData.elements.pan.x Number Required Mutable The element's x-axis position.
    graphData.elements.pan.y Number Required Mutable The element's y-axis position.
    graphData.elements.boxSelectionEnabled Boolean Required Mutable Specifies whether box selection is enabled.
    graphData.elements.renderer Object Required Mutable The renderer object.
    graphData.elements.renderer.name String Required Mutable The renderer name.
    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.

    Read All DaVinci Flow Versions

    Read One DaVinci Flow Version

    Read DaVinci Flow Version Details

    Revert DaVinci Flow Version

    Export a DaVinci Flow Version

    Add a DaVinci Flow Version Alias

    Delete DaVinci Flow Version

    DaVinci Admin Applications

    PingOne DaVinci Admin Applications service provides endpoints to create, read, update, and delete DaVinci applications. This service also includes endpoints to rotate the application key and application secret values.

    A DaVinci application configuration is the link between your site and the sign-on flows you have created in DaVinci. The application configuration contains settings to determine how external sites can send requests for flows, what flows can be requested, and how users and resources from other sites are managed.

    DaVinci Admin applications data model properties

    Property Type? Required? Mutable? Description
    apiKey Object Optional Mutable The collection of API keys associated with this application resource.
    apiKey.enabled Boolean Optional Mutable Specifies whether the API key for this appliction is enabled.
    apiKey.value String Optional Mutable The value of the API key.
    createdAt Date N/A Read only The time when the variable was created.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    id String N/A Read only The variable ID.
    name String Required Mutable The variable name.
    oauth Object Optional Mutable The OAuth configuration for this application resource.
    oauth.clientSecret String Optional Mutable The client secret used by this application resource.
    oauth.redirectUris Array Optional Mutable The list of redirect URIs configured for this application resource.
    oauth.logoutURIs Array Optional Mutable The list of logout URIs configured for this application resource.
    oauth.scopes Array Optional Mutable The list of OAuth scopes configured for this application resource.
    oauth.grantTypes Array Optional Mutable The list of OAuth grant types configured for this application resource.
    oauth.spjwksUrl Array Optional Mutable A URL to retrieve JWKS keys to verify the authorization request signature. This option takes precedence over spjwksOpenid property if both are set.
    oauth.spJwksOpenid Array Optional Mutable A set of JWKS keys to verify the authorization request signature. This property is ignored if spjwksUrl is set.
    updatedAt Date N/A Read only The time when the variable was modified.
    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.

    Create DaVinci Application

    Rotate DaVinci Application Key

    Rotate DaVinci Application Secret

    Read DaVinci Applications

    Read One DaVinci Application

    Update DaVinci Application

    Delete DaVinci Application

    DaVinci Admin Application Flow Policies

    PingOne DaVinci Admin Application Flow Policies service provides endpoints to create, read, update, and delete DaVinci application flow policies. Application flow policies specify which flows are run through the application. A flow policy is an entity that points to one or more flows or versions of flows.

    DaVinci Admin application flow policies data model properties

    Property Type? Required? Mutable? Description
    createdAt Date N/A Read only The time when the flow policy was created.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    id String N/A Read only The flow policy ID.
    name String Required Mutable The flow policy name.
    flowDistributions Array Optional Immutable An array of flow distribution properties that are a part of this flow policy.
    flowDistributions.id String Optional Immutable The flow ID associated with this flow policy.
    flowDistributions.weight Number Optional Mutable The weight that is assigned to the current flow in the flow policy.
    flowDistributions.version String Optional Mutable The version of the flow to be used in the flow policy.
    flowDistributions.successNodes Array Optional Mutable An array of node IDs in the flow that indicate a successful execution of the flow policy.
    flowDistributions.successNodes.id Array Optional Mutable The node ID.
    flowDistributions.ip Array Optional Mutable An array of IP addresses to create a whitelist of IP addresses from which flow executions can be performed.
    status String Optional Mutable The status of the flow policy. Options are Enabled and Disabled.
    trigger Object Optional Immutable The trigger associated with the flow.
    trigger.type String Optional Immutable If the trigger type is set to AUTHENTICATION, you invoke the flow through PingOne OpenID Connect or SAML endpoints.
    updatedAt Date N/A Read only The time when the flow policy was modified.

    DaVinci Admin application flow policy event data model properties

    Property Type? Required? Mutable? Description
    environment Object N/A Read only The environment object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    events Object N/A Read only The DaVinci event object.
    events.id String N/A Read only The DaVinci event ID.
    events.timestamp Date N/A Read only A UTC timestamp that specifies when the event was logged.
    flow Object N/A Read only The DaVinci flow object.
    flow.id String N/A Read only The DaVinci flow ID.
    flow.version Number N/A Read only The DaVinci flow version number.
    totalCount Number N/A Read only The total number of flow executions.
    successCount Number N/A Read only The total count of success nodes reached in flow executions.
    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.

    Create DaVinci Application Flow Policies

    Read DaVinci Application Flow Policies

    Read DaVinci Application Flow Policy Events

    Read One DaVinci Application Flow Policy

    Update DaVinci Application Flow Policy

    Delete DaVinci Application Flow Policy

    DaVinci Admin UI Templates

    You can create user interface (UI) templates that match your company style and branding, which you can include in flows using an HTTP connector. The PingOne DaVinci Admin UI Templates service provides endpoints to create, read, and delete DaVinci UI templates.

    DaVinci Admin UI templates data model properties

    Property Type? Required? Mutable? Description
    createdAt Date N/A Read only A UTC string that specifies the time when the DaVinci UI template was created.
    description String Optional Mutable The UI template description.
    environment Object N/A Read only The DaVinci company ID (environment ID) object.
    environment.id String N/A Read only The DaVinci company ID, which is the PingOne environment ID.
    id String N/A Read only The DaVinci UI template ID.
    name String Required Mutable The UI template name.
    inputSchema String Optional Mutable A JSON representation of the input schema defined in this template.
    outputSchema String Optional Mutable A JSON representation of the output schema defined in this template.
    script String Optional Mutable Javascript code utilized by this template.
    style String Optional Mutable The CSS used in flows that are associated with this template.
    template String Optional Mutable The HTML template to me rendered.
    updatedAt Date N/A Read only A UTC string that specifies the time when the UI template was last modified.
    validationRules Array Optional Mutable The validation rules object.
    validationRules.propertyName String Required Mutable The name of the property to which the validation rule applies.
    validationRules.rules Array Required Mutable The rules object in which the validation rules elements are defined.
    validationRules.rules.ruleName String Required Mutable The name of the rule. Options are presence, email, length, format, and equality.
    validationRules.rules.message String Optional Mutable The rule message that displays if the required property is not present or if the property is not a valid email. For length rules, enter a minimum, maximum, or exact value for the property and a validation message that is displayed for each length restriction that is not met. For format rules, enter the regex that defines the required format and the validation message that displays if the property does not match the format. For equality rules, enter the other property that this property must match, and the validation message that displays if the properties do not match.
    validationRules.rules.attribute String Optional Mutable The property to check when applying the equality rule.
    validationRules.rules.pattern String Optional Mutable The pattern to match when applying the format rule.
    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.

    Create DaVinci UI Template

    Read DaVinci UI Templates

    Read One DaVinci UI Template

    Delete DaVinci UI Template

    PingOne Authorize

    PingOne Authorize provides customers with a fine-grained, attribute-based, dynamic authorization decisioning capability. PingOne Authorize moves per-transaction authorization logic from customer applications to PingOne, enabling centralized control of authorization policy and reuse of policy across applications and contexts.

    Use Cases

    PingOne Authorize Policy Decision Service

    PingOne Authorize provides customers with a fine-grained, attribute-based, dynamic authorization decisioning capability. PingOne Authorize moves per-transaction authorization logic from customer applications to PingOne, enabling centralized control of authorization policy and reuse of policy across applications and contexts.

    This service provides the following operations:

    Runtime evaluation

    Decision endpoint management

    • Creation of decision endpoints that allow efficient evaluation of policies developed in the PingOneAuthorize Policy Editor Service.

    • Control over which version of the policies are deployed to each decision endpoint, giving your organization control over how and when policies are rolled out.

    For more information, see Policy Decision Management.

    Policy Decision Management

    The PingOne policy decision service provides operations to create, read, update and delete decision policy versions in PingOne.

    Policy decision service data model
    Property Type? Required? Mutable? Description
    alternateId UUID Optional Mutable A string that specifies alternative unique identifier for the endpoint, which provides a method for locating the resource by a known, fixed identifier.
    authorizationVersion.id UUID Optional Mutable A string that specifies the ID of the Authorization Version deployed to this endpoint. Versioning allows independent development and deployment of policies. If omitted, the endpoint always uses the latest policy version available from the policy editor service.
    authorizationVersion.href String Optional Mutable A string that specifies the request URL for the authorization version endpoint.
    authorizationVersion.title String Optional Mutable A string that specifies the title for the authorization version response.
    authorizationVersion.type String Optional Mutable A string that specifies the content type for the authorization version response.
    description String Required Mutable A string that specifies the description of the policy decision resource.
    id UUID Required Mutable A string that specifies the resource’s unique identifier.
    name String Required Mutable A string that specifies the policy decision resource name.
    owned Boolean Optional Mutable A boolean that when true restricts modifications of the endpoint to PingOne-owned clients.
    policyId UUID Optional Mutable A string that specifies the ID of the root policy configured for this endpoint. If omitted, the policy editor service decides on a suitable default.
    recentDecisionsEnabled Boolean Optional Mutable A boolean that specifies whether to show recent decisions.
    recentDecisions.href String Optional Mutable A string that specifies the request URL for the recent decisions endpoint.
    recentDecisions.title String Optional Mutable A string that specifies the title for the recent decisions response.
    recentDecisions.type String Optional Mutable A string that specifies the content type for the recent decisions response.
    recordRecentRequests Boolean Required Mutable A boolean that specifies whether to record a limited history of recent decision requests and responses, which can be queried through a separate API.
    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    decision-endpoints DECISION_ENDPOINT.CREATED
    decision-endpoints DECISION_ENDPOINT.UPDATED
    decision-endpoints DECISION_ENDPOINT.DELETED
    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.

    Create Decision Endpoint

    Read All Decision Endpoints

    Read One Decision Endpoint

    Read Recent Decisions

    Read One Recent Decision

    Read All Policy Decision Service Configuration Data

    Read One Policy Decision Service Configuration Data

    Update Decision Endpoint

    Delete Decision Endpoint

    Policy Decision Authorization

    The PingOne policy decision service provides an action for runtime evaluation of decision requests against a given policy decision resource.

    Policy decision evaluation request data model

    Property Type? Required? Mutable? Description
    parameters Object Required Mutable An object that specifies the evaluation parameters required by the policy.
    userContext.user.id UUID Optional Mutable A string that specifies the user's unique identifier.

    Policy decision evaluation response data model

    Property Type? Required? Mutable? Description
    authorizationVersion.id UUID Optional Mutable A string that specifies the ID of the authorization version deployed to this endpoint. Versioning allows independent development and deployment of policies. If omitted, the endpoint always uses the latest policy version available from the policy editor service.
    id UUID Required Mutable A string that specifies the resource's unique identifier.
    correlationId UUID Optional Mutable A string that specifies the decision evaluation correlation ID.
    decision String Required Mutable A string that specifies the decision result. Options are PERMIT, DENY, NOT_APPLICABLE, and INDETERMINATE.
    elapsedMicroseconds Integer Optional Mutable An integer that specifies the evaluation duration in microseconds.
    status.code String Optional Mutable A string that specifies the status. Options are OKAY, MISSING_ATTRIBUTE, TYPE_CONVERSION_ERROR, PROCESSING_ERROR, and TIMEOUT.
    status.message String Optional Mutable A string that specifies the description of the error.
    statements.id UUID Required Mutable A string that specifies the statement's unique identifier.
    statements.name String Required Mutable A string that specifies the statement name.
    statements.code UUID Optional Mutable A string that specifies the the statement code. Options are ANSWER.
    statements.payload Object Optional Mutable An object that specifies statement payload.
    timestamp String Optional Mutable A string that specifies the time the evaluation was executed.

    Policy decision evaluation related resource links

    Link Description
    profile A string that specifies the URL for the decision request's associated profile.
    authorizationVersion.href A string that specifies the URL for the authorization version endpoint.
    authorizationVersion.profile A string that specifies the URL for the authorization version profile.
    policy.href A string that specifies the URL for the policy endpoint.
    policy.profile A string that specifies the URL for the policy profile.
    statements.href A string that specifies the URL for the statements endpoint.
    statements.profile A string that specifies the URL for the statements profile.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    decision-endpoints DECISION_ENDPOINT.DECISION_REQUEST_EVALUATED
    authorize-editor ENVIRONMENT.INITIALIZED

    The decision event format returned by a DECISION_ENDPOINT.DECISION_REQUEST_EVALUATED event uses terse keys to reduce storage requirements. The following table explains the meaning of each key returned in the decision event response.

    Key Description
    enm The name of the endpoint against which the decision request was evaluated.
    eid The ID of the endpoint against which the decision request was evaluated.
    pid The ID of the PingOne Authorize Policy that was deployed to the endpoint at the time the decision request was evaluated.
    ver The ID of the version that was deployed to the endpoint at the time the decision request was evaluated.
    dec The overall decision produced.
    sce The JSON object describing the scenario (the decisions produced by individual policies and rules that contributed to the overall decision).
    sce.P The list of the IDs of the policies and rules that produced the decision PERMIT.
    sce.D The list of the IDs of the policies and rules that produced the decision DENY.
    sce.I The list of the IDs of the policies and rules that produced the decision INDETERMINATE.
    exe The time taken to evaluate the decision request (in microseconds).
    svc The JSON array giving the names and values of PingOne Authorize Services that were invoked as part of the decision request evaluation.
    svc.n The service name.
    svc.v The service value.

    Response codes

    Code Message
    200 Successful operation.
    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.

    Evaluate a Decision Request

    PingOne Authorize API Access Management

    The PingOne Authorize API access management service provides tools to externalize the management and evaluation of access control policies for HTTP-based APIs. The access control policies defined in the API Service configuration are enforced through an API gateway, which delegates policy evaluation using a Ping Identity-provided integration kit that connects with the PingOne API.

    The integration kit installed in your API gateway authenticates to PingOne. You configure a gateway and obtain a gateway credential. This credential is used to configure the API gateway integration kit. For more information, see PingOne Authorize API Gateway Integration Kits.

    To create a gateway resource, see Create API Gateway Integration. In addition, API access management also uses the gateways credentials service. For more information, see Gateway Credentials.

    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.

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

    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.

    Create API Service

    Read API Services

    Read One API Service

    Update API Service

    Delete API Service

    API Service 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.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.

    Create API Server Operation

    Authorize

    Read API Service Operation

    Authorize

    Read All API Service Operations

    Authorize

    Update API Service Operation

    Authorize

    Delete API Service Operation

    Authorize

    API Server Deployment

    The PingOne /environments/{{envID}}/apiServers/{{apiServerID}}/deployment endpoint provides operations to read and deploy an API service resource.

    To create, modify, or delete an API service resource, see API services.

    API service deployment 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.
    authorizationVersion.id String Optional Read-only The UUID of the last deployed policy authorization version. This is present only if custom polcies are enabled and the API service has been deployed at least once.
    decisionEndpoint.id String Required Read-only The UUID of the decision endpoint.
    deployedAt Date Optional Read-only The time of most recent successful deployment. Null if the API service has never been successfully deployed.
    policy.id String Optional Read-only The ID of the root policy.
    status.code String Required Read-only The deployment status code. For possible values, see Deployment status codes.
    status.error Object Optional Read-only Error details returned if the last deployment request failed.
    status.error.id String Required Read-only A unique identifier for the error.
    status.error.code String Required Read-only A general fault code that identifies the the type of error. See Error codes.
    status.error.message String Required Read-only A short human-readable description of the error.

    API service deployment codes

    Status code Description
    POLICIES_CREATE_IN_PROGRESS The policy bundle for the API service's managed policies is being created.
    DECISION_ENDPOINT_CREATE_IN_PROGRESS A decision endpoint is being created for the API service.
    DECISION_ENDPOINT_UPDATE_IN_PROGRESS The API service's decision endpoint is being updated.
    DEPLOYMENT_SUCCESSFUL The API service's policies have been successfully deployed.
    DEPLOYMENT_FAILED HAP-MGMT was unable to deploy the API service's policies.
    DEPLOYMENT_UNINITIALIZED A deployment has not yet been attempted.

    Deploy API Service

    Authorize

    Retrieve Deployment Status

    Authorize

    PingOne Authorize Application Resources and Roles

    The PingOne Authorize application resources and roles service provides endpoints to define custom roles and permissions within PingOne to protect external application resources.

    To create and manage application roles and permissions, see:

    • View application resources

      Provides endpoints to list the representations of external applications in PingOne. For create, update, and delete operations for application resources, see Application Resources.

    • Application resource permissions

      Provides endpoints to define and manage permissions on the application resource.

    • Application roles

      Provides endpoints to define and manage application roles in PingOne. Roles contain application permissions. Application roles can be assigned to PingOne users.

    • Application roles permissions

      Provides endpoints to define and manage access control permissions, expected to be defined by a customer application developer. An application permission is comprised of an action and a protected resource, such as read:accounts. When a permission is added to a role, it creates a role entry. A subject assigned to a role is authorized for the permissions represented by the role's entries.

    • Application role assignments by role

      Provides an endpoint to read application role assignments by role. The endpoint specifies a role ID in the request URL and the operation returns the role assignments associated with the identified role.

    • User application role assignments

      Provides endpoints to define and manage application role assignments associated with user resources.

    Application Resources (Authorize)

    The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationResources endpoint provides operations to read application resources in PingOne. For information about create, update, and delete operations for application resources, see Create Application Resource, Update Application Resource, and Delete Application Resource.

    API application resources data model

    Property Type? Required? Mutable? Description
    description String Optional Mutable The application resource's description.
    id String N/A Read only The resource's unique identifier.
    name String Required Mutable The application resource name. The name value must be unique.
    parent Object Required Read only The application resource's parent.
    parent.type String Required Read only The application resource's parent type. Options are PING_ONE_RESOURCE.
    parent.id String Required Read only The application resource's parent 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.

    Read Application Resources

    Read One Application Resource

    Application Resources Permissions (Authorize)

    The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationResources/{{appResourceID}}/permissions endpoint provides operations to create, read, update, and delete application resource permissions in PingOne.

    Application resources permissions data model

    Property Type? Required? Mutable? Description
    action String Required Mutable The action associated with this permission.
    description String Optional Mutable The resource's description.
    environment.id String N/A Read-only The unique identifier for the associated environment.
    id String N/A Read-only The resource's unique identifier.
    key String N/A Read-only The resource.name:action pair of the permission.
    resource Object N/A Read-only An object that identifies the associated application resource.
    resource.id String N/A Read-only The ID for the associated application resource.
    resource.name String N/A Read-only The name of the associated application resource.

    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.

    Create Application Permissions

    Read Application Permissions

    Read One Application Permission

    Update Application Permission

    Delete Application Permission

    Application Roles

    The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationRoles endpoint provides operations to create, read, update, and delete application roles in PingOne.

    Application roles data model

    Property Type? Required? Mutable? Description
    description String Optoinal Mutable The description of the application role.
    id String N/A Read-only The ID of the application role.
    name String Required Mutable The name of the application role.

    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.

    Create Application Role

    Read Application Roles

    Read Application Role Users

    Read One Application Role User

    Read One Application Role

    Update Application Role

    Delete Application Role

    Application Roles Permissions

    The PingOne Authorize {{apiPath}}/environments/{{envID}}/applicationRoles/{{appRoleID}}/permissions endpoint provides operations to add, read, and delete the permissions associated with application roles.

    Application roles permissions data model

    Property Type? Required? Mutable? Description
    action String N/A Read-only The action associated with this permission.
    description String N/A Read-only The permission description.
    id String N/A Read-only The permission's unique identifier.
    key String N/A Read-only The resource.name:action pair of the permission.
    resource Object N/A Read-only An object that identifies the associated application resource.
    resource.id String N/A Read-only The ID of the resource associated with this role.
    resource.name String N/A Read-only The name of the resource associated with this role.

    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.

    Create Application Role Permission

    Read Application Role Permissions

    Delete Application Role Permission

    Application Role Assignments

    The PingOne Authorize{{apiPath}}/environments/{{envID}}/applicationRoles/{{appRoleID}}/assignments endpoint provides operations to read application role assignments in PingOne.

    Appliction role assignments data model

    Property Type? Required? Mutable? Description
    id String N/A Read-only The ID of the API server operation. This is randomly generated when the operation is created.
    role Object N/A Read only The role associated with the role assignment.
    subject Object N/A Read only The user associated with the role assignment.

    Response codes

    Code Message
    200 Successful operation.
    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.

    Read Application Role Assignments by Role

    PingOne MFA

    The PingOne MFA services provide capabilities for enabling MFA actions in authentication flows, configuring MFA settings and policies, and specifying MFA devices.

    For MFA authentication:

    • The /deviceAuthentications endpoint initiates and completes an MFA action without requiring a call to the PingOne authorize service. It supports actions to select a supported MFA device device type and to validate a one-time passcode (OTP). See MFA Device Authentications.

    For MFA policies and settings:

    • The MFA settings endpoint supports operations to read, update, and reset the PingOne MFA settings associated with a specified environment. See MFA Settings.

    • The Device authentication policies (identified in the PingOne UI as "MFA Policies") enable you to configure different settings per MFA authentication method, according to your security policies. See Device Authentication Policies.

    For MFA device management:

    • The enable user settings (MFA) control whether a user can authenticate using MFA actions. This endpoint enables or disables MFA capability. see Enable Users MFA.

    • The MFA devices service defines the MFA method or methods associated with a user, such as email, SMS, voice, or other MFA device types for use in an MFA flow. See MFA Devices.

    • To enable multi-factor authentication (MFA) via push notification on a native device, the user resource must have a native device and an application associated with its user ID. The association is implemented with a pairing key. See MFA Pairing Keys.

    Authentication methods

    PingOne MFA supports the following authentication methods:

    Authentication Method Reference (amr) Description
    EMAIL OTP through email
    MCA Multiple-channel authentication, indicating that an out-of-band operation through mobile push, either interactive or "silent"
    MFA Multi-factor authentication, indicating some MFA method, as opposed to a Bypass scenario
    OTP Time-based one-time passcode using an authenticator application or mobile OTP
    SMS OTP through SMS text message
    SWK Software-secured key, indicating device authorization using a trusted mobile device
    TEL OTP through a phone call
    USER User presence test, indicating an interactive push notification approved by the user, as opposed to a non-interactive "silent" push notification

    Use Cases

    Enable Users MFA

    The multi-factor authentication settings (MFA) control whether a user can authenticate using MFA actions. This endpoint enables or disables MFA capability.

    For information about user MFA device management, see MFA devices.

    MFA settings data model

    Property Type Required? Mutable? Description
    id String Required Immutable The user resource’s unique identifier.
    mfaEnabled Boolean Required Mutable Whether multi-factor authentication is enabled. This attribute is set to ‘false’ by default when the user is created.

    Response codes

    Code Message
    200 Successful operation.
    204 Successfully removed. No content.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Read User MFA Enabled

    Update User MFA Enabled

    MFA Bypass for User

    Allow MFA Bypass for User

    Check MFA Bypass Status for User

    MFA Devices

    To enable multi-factor authentication (MFA), the user resource must have an MFA method associated with its user ID. PingOne supports email, SMS, voice, TOTP authenticator application, and native application method types for use in an MFA flow. Multiple MFA methods can be associated with a user ID. MFA methods must be in the active state to be used in the multi-factor login flow.

    With this API, MFA methods are called MFA devices. The devices endpoints provide operations to manage device resources associated with a specified user ID. You need the Identity Data Admin role to perform operations on device resources.

    Device order

    With the release of the device order feature (Jan 11, 2021), the active devices of most users now have an order (first...last). By default, the order is according to the device activation time (oldest...newest). Each subsequently activated device is appended to the end of the order list. The first device on the list is designated the default device. In most cases, the default device is automatically used for authentication; users no longer need to select a device.

    There are a small number of users whose devices do not have a default order with this feature. If a user has more than one active device as of the release of the device order feature, the current active devices and subsequently activated devices have no order. The user therefore has no default device and must choose a device each time they authenticate. In this case, the order must be explicitly set (see Setting device order).

    Cases where the default device is not used for authentication

    In most cases, the default device is automatically used for authentication. However, there are two exceptions:

    • If authenticating from a native app and device authorization is enabled, the native device is used for seamless authentication (see Automatic device authorization under PingOne MFA Native SDK Flows).
    • If the user is paired with a FIDO2 platform device and a session token cookie exists on the browser, the FIDO2 platform device is used for authentication even if it is not the default device.

    Setting device order

    The operation POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.reorder+json explicitly orders a user's existing active devices according to the request body. The active device listed first becomes the default device.

    After this operation explicitly sets device order, subsequently activated devices are appended to the end of the order list. You can use this operation to explicitly reorder active devices as many times as needed.

    Retrieving an ordered list of devices

    The operation GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices returns the list of active devices sorted in their order, with the default device listed first. Devices with a status of ACTIVATION_REQUIRED are listed after the active devices, in no particular order. If devices have no order, GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices returns the list of devices in no particular order.

    You can expand the GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results with the expand=order query parameter. The response is then expanded to contain an array of activated device IDs listed according to device order. If devices have no order, an empty array is returned.

    Deleting a default device

    If the default (first) device is deleted, the second active device on the order list becomes the default device.

    Removing device order

    The operation POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.order.remove+json removes the ordering on a user's active devices. With the execution of this operation, the user no longer has a default device.

    Custom device pairing notification with device creation

    To send a custom device pairing notification when a new email, SMS or voice device is created, add the notification property to the request body of POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices. The status of the created device must be ACTIVATION_REQUIRED.

    {
    “notification”: {
        “template”: {
            “locale”: “en”,
            “variant”: “variant_B”
            "variables": {
                        "sum": "1,000,000",
                        "currency": "USD",
                        "recipient": "Charlie Parker"
            }
       }
    }
}

    When the device is created, a request is executed to select the content for the notification. The notification template is device_pairing. The deliveryMethod is Email, SMS or Voice, depending on the device created. The locale, variant, and all dynamic variables are defined in notification.

    For more information on content selection, see Runtime logic for content selection. For more information on dynamic varables, see Dynamic variables.

    Device failure in flows

    When the flow returns a NO_USABLE_DEVICES error, and the user has devices that are temporarily unavailable (for example, the device is locked because of too many invalid OTP retries), the IDs of these devices are returned as part of the response.

    In the flow response, the status property returns FAILED, and the error message includes the NO_USABLE_DEVICES error code. The following samples show common error messages for a device failure with identified unavailableDevices:

    "status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Couldn't find authenticating device for user: {{userID}}",
      "unavailableDevices": [
            {
                "id": "edccc773-6f31-4d28-a8e1-0f427d9a9df8"
            }
        ]
    },

    "status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Daily limit of SMS authentication attempts has been exceeded",
        "unavailableDevices": [
            {
                "id": "7ea99e29-6f8f-42be-af75-232588235e30"
            }
        ]
    },

    Device properties

    Property Type Required? Mutable? Description
    block.status String Optional Read-only Whether the device is currently blocked. The possible values are BLOCKED and UNBLOCKED.
    block.blockedAt Date Optional Read-only The date and time that the device was blocked.
    createdAt Date N/A Read-only The date the device was created.
    environment.id String N/A Read-only The environment ID associated with the device resource.
    id String N/A Read-only The device resource’s unique identifier.
    lock.status String N/A Read-only Indication of whether the device is currently locked out due to too many failed attempts. Values are LOCKED, UNLOCKED.
    lock.expiresAt Date N/A Read-only For devices that are currently locked out, the date and time when the lock will expire.
    lock.reason String N/A Read-only For devices that are currently locked out, provides the reason for the lock. Values are OTP or PUSH. OTP means that the user passed the defined limit on the number of unsuccessful OTP tries. PUSH means that the user passed the limit on the number of push notifications that can be declined or ignored within the defined time period.
    nickname String Optional Mutable Identifies the authentication method in the UI. If defined, this string also appears on the authentication screens. This property has a limit of 100 characters. All characters are supported. An empty string is also supported to delete the value. Use Update Device Nickname to set this property.
    notification.policy.id String Optional Mutable The policy ID for the notification.
    policy.id String Optional Mutable The device authentication policy ID associated with the device resource. Specifying a device authentication policy ID applies that policy on the API, which determines the MFA methods and mobile applications that are allowed. This property is not returned with GET operations and cannot be used with PUT operations. Currently, if a policy ID is not specified on the request, the environment policy is used. However, this behavior is temporary; it is highly recommended that you specify a policy ID in the POST operation request body.
    status String Optional Mutable The device status. Options:
    • ACTIVE
    • ACTIVATION_REQUIRED
    1. If the actor makes the request on behalf of another user (typically using a Worker App), you can use either of the values:
      • ACTIVE (default, if not provided): The device is pre-paired for the user. The user is not required to activate the device before using it for authentication for the first time.
      • ACTIVATION_REQUIRED: The user must activate the device before using it for authentication for the first time.
    2. If the actor making the request is the same user for whom the device is created, the status can only be ACTIVATION_REQUIRED (default, if not provided). Thus in this case, the user is required to activate the device before using it for authentication for the first time.

    If the status is ACTIVATION_REQUIRED, you can use the notification property during device creation to create a custom device pairing notification. This is only applicable with SMS, Voice and Email devices. The notification property is not returned with GET operations and cannot be used with PUT operations. For more information, see Custom device pairing notification with device creation.

    Note: An actor making a self request must have an access token that includes the p1:create:device scope.
    tokenType String N/A Read-only For devices of type OATH_TOKEN. Possible values are HOTP and TOTP.
    type String Required Mutable The device type. Options:
    • EMAIL
    • FIDO2
    • MOBILE
    • OATH_TOKEN (for PingID users)
    • SMS
    • TOTP (third-party TOTP authenticator applications)
    • VOICE
    • WHATSAPP
    • PLATFORM - FIDO2 bound biometrics devices (deprecated, use FIDO2 instead)
    • SECURITY_KEY - FIDO2 or U2F security key devices (deprecated, use FIDO2 instead)
    updatedAt Date N/A Read-only The date the device was last updated.
    user.id String Optional Mutable The ID of the user associated with the device.
    EMAIL device properties

    Devices whose type is EMAIL also have the following properties:

    Property Type Required? Mutable? Description
    email String Required Immutable The email address, which is required during POST only if the device type is EMAIL. The email address must be valid.
    notification Object Optional Immutable Contains notification information. When this property is supplied during device creation, the information within is used to create a custom device pairing notification. For more information, see Custom device pairing notification with device creation.
    notification.template String Optional Immutable An object that contains template parameters.
    notification.template.locale String N/A Read-only The ISO language code (string) used for the device created notification. For example, en.
    notification.template.variant String N/A Read-only The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
    notification.template.variables Map[String, String] Optional Read-only An object of name-value pairs that defines the dynamic variables used by the content variant. For more information on dynamic variables, see Dynamic variables.
    testMode Boolean Optional Mutable To simplify automated testing of your applications, you can create dedicated testing devices. When you use the API to send authentication requests to such a device, the OTP is not sent to the actual device, but instead is returned as part of the body of the response. To specify that a device should serve as a testing device, set the value of testMode to true. If this parameter is not provided, the default value is false. For dedicated testing devices, the response to authentication requests includes the OTP value in the field test.otp.
    test.otp Integer Optional Read-only If you use the testMode parameter to create a dedicated testing device, and status is set to ACTIVATION_REQUIRED in the request, the response will include test.otp, which is the passcode that you should use to activate the device.
    SMS/Voice device properties

    Devices whose type is SMS or VOICE also have the following properties:

    Property Type Required? Mutable? Description
    phone String Required Immutable The phone number, which is required only if the device type is SMS or VOICE. It must be a well-formed phone number consisting of a leading plus sign, 1 to 3-digit country code, and 4 to 14-digit phone number (e.g. +11235557890).
    extension String Optional Immutable When creating a device of type VOICE, use extension for phone numbers that also have an extension. Can include digits, commas, #, and *. For nested extensions, separate the parts with a comma.
    notification Object Optional Immutable Contains notification information. When this property is supplied during device creation, the information within is used to create a custom device pairing notification. For more information, see Custom device pairing notification with device creation.
    notification.template String Optional Immutable Contains template parameters.
    notification.template.locale String Optional Read-only The ISO language code used for the device created notification. For example, en.
    notification.template.variant String Optional Read-only The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
    notification.template.variables Map[String, String] Optional Read-only An object of name-value pairs that defines the dynamic variables used by the content variant. For more information on dynamic variables, see Dynamic variables.
    testMode Boolean Optional Mutable To simplify automated testing of your applications, you can create dedicated testing devices. When you use the API to send authentication requests to such a device, the OTP is not sent to the actual device, but instead is returned as part of the body of the response. To specify that a device should serve as a testing device, set the value of testMode to true. If this parameter is not provided, the default value is false. For dedicated testing devices, the response to authentication requests includes the OTP value in the field test.otp.
    test.otp Integer N/A Read-only If you use the testMode parameter to create a dedicated testing device, and status is set to ACTIVATION_REQUIRED in the request, the response will include test.otp, which is the passcode that you should use to activate the device.
    Native device properties

    Devices whose type is MOBILE also have the following properties:

    Property Type Required? Mutable? Description
    apiVersion String Required Mutable The native SDK API version.
    application.id String Required Immutable The ID of the native application associated with this device.
    application.nativeName String Optional Mutable The name of the application retrieved from the native app in runtime.
    application.pushSandbox Boolean Optional Immutable Indicates if the native application uses production or sandbox push credentials (if the app was built and installed by a developer from Xcode, or installed ad hoc). Only relevant on iOS devices.
    application.version String Optional Mutable The version of the application retrieved from the native app in runtime.
    deviceIntegrityState.advice String N/A Read-only If available, Google advice for the deviceIntegrityState.reason.
    deviceIntegrityState.compromised String N/A Read-only Indicates if the device's integrity is compromised:
    • TRUE
    • FALSE
    • UNKNOWN
    deviceIntegrityState.reason String N/A Read-only Indicates the cause of the device's current integrity state:
    • JAILBROKEN
    • BASIC_INTEGRITY
    • CTS
    • DATA_UNAVAILABLE
    • SAFETYNET_UNAVAILABLE
    • SAFETYNET_ERROR
    • SAFETYNET_VALIDATION_ERROR
    • DATA_EXPIRED
    • INTERNAL_ERROR
    • INVALID_CERTIFICATE_DIGEST
    • INVALID_PACKAGE_NAME
    deviceIntegrityState.timestamp Date N/A Read-only The date and time (UTC) of the latest integrity check for the device.
    integrityStateCurrent String N/A Read-only Used for internal PingOne purposes.
    locale String Optional Mutable The device's locale.
    lockEnabled Boolean Optional Mutable Whether the device is lock enabled.
    logs.expiresAt Date N/A Read-only The date and time the request for expires, if the logs have not been sent yet. The value is set at 24 hours from the time of the request, and remains only while the logs.status is PENDING. logs.expiresAt is reset when the logs are sent, or when the system date reaches the request's expiry time.
    logs.level String Optional Mutable The level of log detail. Values:
    • VERBOSE
    • DEBUG
    • INFO (default)
    • WARN
    • ERROR
    logs.status String Optional Mutable The returned status of a request for logs from a particular user device. Possible values:
    • PENDING: The request for logs was issued. When the user connects to the app, it will send the logs.
    • RECEIVED: The logs were sent from the device, and received.
    manufacturer String N/A Read-only The manufacturer of the device.
    model.marketingName String Required Read-only The model's marketing name.
    model.name String Required Read-only The device's model name.
    name String N/A Read-only The device name given by the manufacturer.
    notificationProvider String N/A Read-only The messaging system used for push notifications. For the possible values, see the type property in the MFA push credentials data model.
    os.type String Required Read-only The device's operating system.
    os.version String Required Mutable The device's operating system version.
    otpEnabled Boolean N/A Read-only Whether OTP authentication is enabled for the device.
    pushEnabled Boolean N/A Read-only Whether push is enabled for the device.
    pushToken String Optional Mutable The push token for this application on this device (for internal use).
    rooted (Deprecated) Boolean Required Mutable Use deviceIntegrityState instead.
    sdkVersion String N/A Read-only The version of the MFA Mobile SDK used.
    Time-based One-time Password (TOTP) authenticator application device properties

    Devices whose type is TOTP also have the following properties:

    Property Type Required? Mutable? Description
    secret String N/A Read-only The unique secret key shared by the prover (token) and the verifier (authentication server). Only returned if the device's activation status is ACTIVATION_REQUIRED. Both the secret and the keyURI values expire after 30 minutes.
    keyUri String N/A Read-only The authenticator key URI, for example, otpauth://totp/abc@example.com?secret={secretValue}. Both the secret and the keyURI values expire after 30 minutes.
    FIDO2 devices

    Devices whose type is FIDO2 also have the following properties:

    Property Type Required? Mutable? Description
    attestation String N/A Read-only Specifies the public key and signed challenge used to complete registration and device activation. Devices with a status of ACTIVATION_REQUIRED are activated using a valid attestation and origin. The attestation is generated by the browser as a response to a specific user action, such as a fingerprint or clicks on the security key. This is a required property for FIDO2 device activation.
    attributes Object N/A Read-only Object returned in the response for FIDO2 devices.
    attributes.isCrossPlatform Boolean N/A Read-only Value is true if the device has ever been cross-platform.
    attributes.previousDeviceType String N/A Read-only Included in the response for devices that were converted to FIDO2 from one of the deprecated device types. Value can be SECURITY_KEY or PLATFORM.
    backup Object N/A Read-only Included in the response, contains the information regarding the backup eligibility of the device.
    backup.backupEligibility Boolean N/A Read-only Whether the public key credential source is allowed to be backed up.
    backup.backupState Boolean N/A Read-only Whether the public key credential source is currently backed up.
    challenge String Optional Immutable If you want to use dynamic linking to attach a unique identifier to the registration of a FIDO device, provide a value for the challenge parameter. The value should be a custom challenge to replace the automatically-generated challenge that is ordinarily used. Must be a valid and unique Base64URL string that decodes to a data array of at least 32 bytes. You can generate a challenge that meets these criteria by adding a random nonce to the registration details to ensure uniqueness and then using SHA-256 to hash the information.
    displayName String N/A Read-only The name displayed for the device in self-service registration and authentication windows. The name is taken from the relevant FIDO2 policy. Returned in the response only for request to read all FIDO2 devices.
    fidoDeviceMetadata Object N/A Read-only For FIDO2 devices that have already been activated, contains metadata for the specific type of FIDO2 authenticator. Included in responses only if the mdsAuthenticatorsRequirements.option was set to a value other than NONE in the FIDO policy that was used when the device was paired. By default, the object contains only the mdsIdentifier field. If you want responses to include additional authenticator-related data, include the expand parameter in your query and set it to fidoDeviceMetadata, for example, GET {{apiPath}}/environments/{{envId}}/users/{{userID}}/devices/{{deviceID}}?expand=fidoDeviceMetadata. When the expand parameter is used, the object containing the data is included in the response under embedded.
    fidoDeviceMetadata.custom Boolean N/A Read-only Indicates whether the authenticator is a custom authenticator that was added to the PingOne global authenticator table.
    fidoDeviceMetadata.mdsIdentifier String N/A Read-only The Authenticator Attestation GUID (AAGUID) for the type of authenticator.
    fidoDeviceMetadata.name String N/A Read-only The name of the authenticator.
    fidoDeviceMetadata.platform Boolean N/A Read-only Indicates whether the authenticator is attached to a platform, as opposed to a cross-platform authenticator.
    fidoDeviceMetadata.protocol String N/A Read-only The FIDO protocol family. The possible values are: uaf, u2f, and fido2.
    fidoDeviceMetadata.uvMethods Array N/A Read-only The relevant user verification methods, such as presence_internal or passcode_external.
    origin String Required Read-only The originating server (for example, https://apps.pingone.com). This property and the attestation property are used to activate FIDO2 devices that have a status of ACTIVATION_REQUIRED. This is a required property for FIDO2 device activation.
    publicKeyCredentialCreationOptions String N/A Read-only A JSON serialization of the client data returned for registering a FIDO2 device with the webauthn navigator.credentials.create API.
    rp Object Optional Immutable Information on the relying party. If not provided, the relying party ID is taken from the associated FIDO2 policy.
    rp.id String Optional Immutable The ID of the relying party. The value should be a domain name, such as example.com (in lower-case characters).
    rp.name String Optional Immutable The relying party's human-readable display name (for example, acme).
    OATH token devices

    OATH tokens can be used only in PingOne environments where a PingID account has been integrated.

    Devices whose type is OATH_TOKEN also have the following properties:

    Property Type Required? Mutable? Description
    oathResync Boolean Optional Immutable When activating an OATH token device that is currently in ACTIVATION_REQUIRED state, you can include the oathResync parameter. When set to true, it instructs PingOne to resync the OATH token that is to be activated if a resync is required. If a resync is necessary, the response to the activation request is an error message indicating that you must provide an additional OTP to complete the process. When this message is returned, run the activate request again, this time including the next OTP for the token, without the oathResync parameter. This second request completes the pairing process, and the status of the device is changed to ACTIVE.
    serialNumber String Required Mutable Value of serialNumber must be the serial number of an OATH token that has already been added to the PingOne environment.
    PLATFORM and SECURITY_KEY webauthn device data model (deprecated, replaced by FIDO2 devices)

    Devices whose type is PLATFORM or SECURITY_KEY also have the following properties:

    Property Type Required? Mutable? Description
    platform String N/A Read-only The type of platform associated with this MFA device. Options are BIOMETRICS, WINDOWS, ANDROID, MAC, and IPHONE. This property applies only to devices in which the type property is set to PLATFORM. The type of platform is based on the User-Agent HTTP header of the request. If it is not possible to identify the platform, the value defaults to BIOMETRICS.
    publicKeyCredentialCreationOptions String N/A Read-only A JSON serialization of the client data returned for registering a FIDO2 device with the webauthn navigator.credentials.create API.
    rp.id String Required Immutable The relying party identifier, which is based on a host's domain name but without a scheme or port (for example, acme.com or login.acme.com).
    rp.name String Required Immutable The relying party's human-readable display name (for example, acme).
    Device order properties
    Property Type Required? Mutable? Description
    order String[] Required Mutable An array of objects that determines the explicit order of a user's devices. The first device listed becomes the default device. This property is used as a body parameter to set the order of existing devices.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    users DEVICE.CREATED
    users DEVICE.UPDATED
    users DEVICE.DELETED
    users DEVICE.LOGS_RECEIVED
    users DEVICE.REORDERED
    users DEVICE.ACTIVATION_OTP_INVALID
    users DEVICE.ACTIVATION_OTP_FAILED

    Response codes

    Code Message
    200 Successful operation.
    400 The request was invalid.
    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.
    500 Unexpected server error.

    Filtering result data

    You can filter GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set.

    SCIM operators can be applied to the following attributes:

    Collection Attribute Supported operators Valid values
    Devices mobilePayload eq (equals) The signed JWT payload from the PingOne Mobile SDK. The payload contains information about a specific device, so the collection returned will always contain just a single device.
    Devices status eq (equals) "ACTIVE", "ACTIVATION_REQUIRED"
    Devices type eq (equals) "SMS", "VOICE", "EMAIL", "TOTP", "MOBILE", "PLATFORM", "SECURITY_KEY"

    The logical operators and and or can also be used to combine filter statements.

    For example, the following URL-encoded SCIM filter returns a list of SMS devices that require activation:

    {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=(status%20eq%20%22ACTIVATION_REQUIRED%22)%20and%20(type%20eq%20%22SMS%22)

    This URL returns the device that matches the information contained in the specified payload from the PingOne Mobile SDK:

    {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=mobilePayload eq "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz..."

    Expanding result data

    You can expand GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results with the expand=<value> query parameter. The following value is supported.

    Value Description
    order The response is expanded to contain an array of activated device IDs listed according to device order. This value is relevant only if the devices are ordered. If devices are not ordered, and empty array is returned. For more information, see Setting device order.

    Create MFA User Device (Voice)

    Create MFA User Device (Email)

    Create MFA User Device (TOTP)

    Create MFA User Device (FIDO2)

    Create MFA User Device (SMS)

    Create MFA User Device (OATH token)

    Create MFA User Device (WhatsApp)

    Create MFA User Device for testing

    Resend Pairing Code

    Set Device Order

    Remove Device Order

    Activate MFA User Device (OATH token)

    Activate MFA User Device

    Activate MFA User Device (FIDO2)

    Unlock MFA User Device

    Block MFA User Device

    Unblock MFA User Device

    Read All MFA User Devices

    Read One MFA User Device

    Update Device Nickname

    Send MFA Device Logs

    Delete MFA User Device

    MFA Pairing Keys

    To enable multi-factor authentication (MFA) via push notification on a native device, the user resource must have a native device and an application associated with its user ID. The association is implemented with a pairing key.

    The pairing key endpoints provide operations to create, read, and remove pairing key resources associated with a specified user ID, native device and application. The examples below show common actions to manage pairing keys.

    Creating a native device with a pairing key

    A user cannot create a native (mobile) device with POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices. The user must create the device with a pairing key:

    1. The user installs a native app with an embedded PingOne MFA Native SDK component.

    2. The user starts an MFA authentication flow and creates a pairing key. See Multi-factor MFA Action in the Developer Guide for more information.

    3. The user scans the pairing key QR code with the native app.

    4. The embedded PingOne MFA Native SDK starts the pairing process where the device resource is created. See PingOne MFA SDK for Android or PingOne SDK for iOS.

    Pairing key data model

    Property Type Required? Mutable? Description
    id String N/A Read-only The resource ID.
    environment.id String N/A Read-only The environment ID.
    code String N/A Read-only The pairing key that the end users should use for pairing their device.
    status String N/A Read-only The status of the pairing key. Valid values:
    • UNCLAIMED
    • CLAIMED
    • FAILED
    error.code String N/A Read-only The code indicating the reason that status is FAILED.
    error.message String N/A Read-only The message indicating the reason that status is FAILED.
    applications String[Array] Optional Mutable The collection of application IDs that can be used with this pairing key.
    user.id String N/A Read-only The user ID.
    policy.id String Optional Mutable A string that specifies the device authentication policy ID associated with the pairing key resource. Specifying a device authentication policy ID applies that policy on the API, which determines the MFA methods and mobile applications that are allowed. This property is not returned with GET operations. Currently, if a policy ID is not specified on the request, the environment policy is used. However, this behavior is temporary; it is highly recommended that you specify a policy ID in the POST operation request body.
    createdAt Date N/A Read-only The date this pairing key was created.
    updatedAt Date N/A Read-only The date this pairing key was last updated.
    expiresAt Date N/A Read-only The date this pairing key expires.

    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.
    500 Unexpected server error.

    Create MFA Pairing Key

    Read One MFA Pairing Key

    Delete MFA Pairing Key

    MFA Device Authentications

    The /deviceAuthentications endpoint initiates and completes an MFA action without requiring a call to the PingOne authorize service. It supports actions to select a supported MFA device device type and to validate a one-time passcode (OTP).

    When a device authentication MFA flow is initiated, the flow returns a status property in the response that identifies the next action in the flow. The following flow states prompt for a specific flow action:

    • OTP_REQUIRED

      For a status value of OTP_REQUIRED, the otp.check action validates the one-time passcode.

    • DEVICE_SELECTION_REQUIRED

      For a status value of DEVICE_SELECTION_REQUIRED, the device.select action prompts the user to select a supported device type for use in a multi-factor authentication flow.

    • ASSERTION_REQUIRED

      For a status value of ASSERTION_REQUIRED, the assertion.check action validates the assertion.

    • PUSH_CONFIRMATION_REQUIRED

      For a status value of PUSH_CONFIRMATION_REQUIRED, a push was sent to the specified mobile device to confirm the authentication.

    • PUSH_CONFIRMATION_TIMED_OUT

      For a status value of PUSH_CONFIRMATION_TIMED_OUT, a push was sent to the specified mobile device, but the mobile device did not answer the push during the allowed timeframe.

    Device authentications data model

    Property Type? Required? Mutable? Description
    aggregateFido2Devices Boolean N/A Read-only Indication of whether the available authentication method list should include only a single generic FIDO2 option rather than including an entry for each paired FIDO2 device. The field is included in the response to the request to initiate an MFA device authentication flow (POST {{authPath}}/{{envID}}/deviceAuthentications).
    application.id String Optional Mutable The requesting application's unique identifier. This identifier is required only during device authorization flows when the mobilePayload value is provided.
    createdAt Date N/A Immutable When the resource was created.
    error Object N/A Read-only The error field indicating the reason for a device authentication failure.
    error.code String N/A Read-only The error code.
    error.message String N/A Read-only The error message.
    id String N/A Read-only The resource's unique identifier.
    mobilePayload String N/A Read-only The JSON that is the result of a getMobilePayload call (mobile app to mobile SDK). Both mobilePayload and applicationId values are required to invoke the device authorization flow using the API.
    notification Object Optional Immutable Holds dynamic notification data.
    notification.clientContext Object Optional Immutable Holds dynamic mobile push data.
    notification.policy.id String Optional Mutable The policy ID for the notification.
    notification.template Object Optional Immutable Holds dynamic template data.
    notification.template.name String Optional Immutable The notification template name.
    notification.template.variant String Optional Immutable The notification template variant.
    notification.template.locale String Optional Immutable The notification template locale.
    notification.template.variables Map Optional Immutable The notification template variables.
    policy.id String Optional Mutable The device authentication policy ID.
    publicKeyCredentialRequestOptions String N/A Read-only A string that specifies the public key credential request options object generated for the selected device that should be used to call the navigator.credentials.get() on the browser to generate the assertion. If you are using dynamic linking to attach a unique identifier to a FIDO transaction, publicKeyCredentialRequestOptions will include the transaction information for your records.
    rp.id String Optional Mutable The ID of the relying party, used for logging in without having to provide a username. The value of the field should be a domain name, such as sample.com. If not provided, the relying party ID is taken from the associated FIDO2 policy.
    selectedDevice.id String Optional Mutable The unique identifier of a user's MFA device. You can use this property to specify that authentication should be carried out with a specific device if the user has more than one.
    selectedDevice.oneTime.type String Optional Mutable For organizations that prefer to maintain their own user device information, you can use the oneTime object to specify how the user should be contacted. The type property indicates the method that should be used for contacting the user. The value can be SMS, VOICE, or EMAIL. If you are using the oneTime object, you should not include the selectedDevice.id property.
    selectedDevice.oneTime.phone String Optional Mutable If selectedDevice.oneTime.type is set to SMS or VOICE, use the phone property to provide the user's phone number.
    selectedDevice.oneTime.email String Optional Mutable If selectedDevice.oneTime.type is set to EMAIL, use the email property to provide the user's email address.
    selectedDevice.oneTime.testMode Boolean Optional Mutable To simplify automated testing of your applications, you can create dedicated testing devices. When you use the API to send authentication requests to such a device, the OTP is not sent to the actual device, but instead is returned as part of the body of the response. To specify that a one-time device should serve as a testing device, set the value of testMode to true. If this parameter is not provided, the default value is false. For dedicated testing devices, the response includes the OTP value in the field test.otp.
    selectedDevice.otp String Optional Mutable Enables the user to enter their OTP when triggering MFA.
    status String N/A Read-only The flow status. Options are DEVICE_SELECTION_REQUIRED, PUSH_CONFIRMATION_REQUIRED, PUSH_CONFIRMATION_TIMED_OUT, OTP_REQUIRED, ASSERTION_REQUIRED, COMPLETED, and FAILED.
    test.otp String N/A Read-only If you are using a test device or you used the testMode parameter to specify that a one-time device should serve as a testing device, the response includes the OTP value in the field test.otp.
    updatedAt Date N/A Immutable When the resource was last updated.
    user.id String Required Mutable The requesting user's unique identifier.
    webAuthn.challenge String Optional Immutable If you want to use dynamic linking to attach a unique identifier to a FIDO transaction, provide a value for the webAuthn.challenge parameter. The value should be a custom challenge to replace the automatically-generated challenge sent with the authentication request. Must be a valid and unique Base64URL string that decodes to a data array of at least 32 bytes. You can generate a challenge that meets these criteria by adding a random nonce to the transaction details to ensure uniqueness and then using SHA-256 to hash the information.
    _embedded.devices Array N/A Read-only The list of authenticating devices.
    _embedded.devices[].otpStatus.status String N/A Read-only Whether or not the device can be used currently for OTP-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.
    _embedded.devices[].otpStatus.reason String N/A Read-only If the status is DISABLED, contains the reason that the device cannot be used for OTP-based authentication, for example, that the application used a version of the MFA SDK that does not support OTP. Relevant only for devices where type is MOBILE.
    _embedded.devices[].pushStatus.status String N/A Read-only Whether or not the device can be used currently for push-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.
    _embedded.devices[].pushStatus.reason String N/A Read-only If the status is DISABLED, contains the reason that the device cannot be used for push-based authentication, for example, that the push option was disabled for the application in the MFA policy. Relevant only for devices where type is MOBILE.
    _embedded.devices[].usableStatus.status String N/A Read-only Whether or not the device can be used currently for authentication. Value returned is ENABLED or DISABLED.
    _embedded.devices[].usableStatus.reason String N/A Read-only If the status is DISABLED, contains the reason that the device cannot be used for authentication, for example, that the defined daily notifications limit has already been reached.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    device-authentications OTP.CHECK_SUCCESS
    device-authentications OTP.CHECK_INVALID
    device-authentications OTP.CHECK_FAILED
    device-authentications PUSH.CONFIRMATION_TIMED_OUT
    device-authentications AUTHENTICATION.CREATED
    device-authentications AUTHENTICATION.UPDATED

    Initialize Device Authentication

    Device Authentication (Custom Notification)

    Device Authentication (No User Name)

    Device Authentication (One-time SMS)

    Device Authentication (One-time Voice)

    Device Authentication (One-time Email)

    Select Device for Authentication

    Validate OTP for Device

    Check Assertion (FIDO Device)

    Cancel Device Authentication

    Read Device Authentication

    MFA Authentication Code

    The /authenticationCodes endpoint provides operations to create, read, and delete an authentication code. The authentication code (which can be a QR code) enables users to sign on without any data entry, such as providing a username, password, or entering a one-time passcode. The user scans the code, and if successful, gains access to an application's services.

    Authentication codes request data model

    Property Type Required? Mutable? Description
    application.id String Required Mutable The ID of a mobile application for which the code is valid; only the specified mobile application can scan the QR code.
    clientContext String Optional Mutable An ObjectNode that provides relevant information to the mobile application that can be shown to application users. For example, Do you want to approve this transaction?. For more information, see Create Authentication Code.
    lifeTime.duration Integer Optional Mutable The length of time for this authentication code to be valid. The minimum value is 10 seconds; the maximum value is 30 minutes; the default is 1 minute. If the lifeTime.duration property is set, a value for lifeTime.timeUnit is required.
    lifeTime.timeUnit String Optional Mutable The time unit for the lifeTime.duration property. Options are SECONDS and MINUTES. If the lifeTime.timeUnit property is set, a value for lifeTime.duration is required.
    userApproval String Optional Mutable Whether the mobile device must verify that the user approves the authentication with the scanned code. Options are REQUIRED and NOT_REQUIRED.

    Authentication codes response data model

    Property Type Required? Mutable? Description
    code String N/A Read-only The authentication code. The code is eight characters in length, and it can include numbers and uppercase letters.
    createdAt Date N/A Read-only When the resource was created.
    environment.id String N/A Read-only The environment's unique identifier.
    expiresAt Date N/A Read-only The expiration time of authentication code.
    id String N/A Read-only The resource's unique identifier.
    status String N/A Read-only The status of the authentication code. Options are UNCLAIMED, CLAIMED, EXPIRED, DENIED, and COMPLETED. The EXPIRED status is active for 5 minutes after the code is no longer valid.
    updatedAt Date N/A Read-only When the resource was last updated.
    uri String N/A Read-only A universal link (for example, https://www.example.com/pingonesdk?authentication_code={{generated token}}). This property can also set a link to a schema application (for example, pingoneapp://pingonesdk?authentication_code={{generated token}}). If a universal link or schema application link is not set, the response does not include the pingonesdk?authentication_code={{generated token}} portion of the URL.
    user.id UUID N/A Read-only The unique identifier of the authenticated user.
    _embedded.device.otpStatus.status String N/A Read-only Whether or not the device can be used currently for OTP-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.
    _embedded.device.otpStatus.reason String N/A Read-only If the status is DISABLED, contains the reason that the device cannot be used for OTP-based authentication, for example, that the application used a version of the MFA SDK that does not support OTP. Relevant only for devices where type is MOBILE.
    _embedded.device.pushStatus.status String N/A Read-only Whether or not the device can be used currently for push-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.
    _embedded.device.pushStatus.reason String N/A Read-only If the status is DISABLED, contains the reason that the device cannot be used for push-based authentication, for example, that the push option was disabled for the application in the MFA policy. Relevant only for devices where type is MOBILE.
    _embedded.device.usableStatus.status String N/A Read-only Whether or not the device can be used currently for authentication. Value returned is ENABLED or DISABLED.
    _embedded.device.usableStatus.reason String N/A Read-only If the status is DISABLED, contains the reason that the device cannot be used for authentication, for example, that the defined daily notifications limit has already been reached.

    For descriptions of other fields under _embedded.device, see MFA Devices.

    For descriptions of fields under _embedded.user, see Users data model.

    Create Authentication Code

    Read Authentication Code

    Delete Authentication Code

    Device Authentication Policies

    Device authentication policies (identified in the PingOne UI as "MFA Policies") enable you to configure different settings per MFA authentication method, according to your security policies.

    Device authentication policy data model

    Property Type Required? Mutable? Description
    authentication.deviceSelection String Optional Mutable The default method that should be used for authentication. Can take one of the following values:
    • DEFAULT_TO_FIRST - use the method that the user set as their default
    • PROMPT_TO_SELECT - always have the user select the method to use if there is more than one method available
    • ALWAYS_DISPLAY_DEVICES - always have the user select the method to use even if there is only one method available
    If this parameter is not provided, the DEFAULT_TO_FIRST option is used.
    default Boolean Required Mutable Whether this is the default policy for Flow Manager.
    email Object Required Mutable Email device authentication policy settings. Offline device (SMS, voice, email, WhatsApp) authentication policy data model
    environment String N/A Read-only The environment ID.
    fido2 Object Required Mutable FIDO device authentication policy settings. FIDO device authentication policy data model
    forSignOnPolicy Boolean Optional Immutable Deprecated.
    id String N/A Read-only The ID of the device authentication policy.
    mobile Object Required Mutable Mobile device authentication policy settings. Mobile authentication policy data model
    name String Required Immutable The device authentication policy's name.
    newDeviceNotification String Optional Mutable Use newDeviceNotification to control whether a user should be notified if a new authentication method has been added to their account. Can take one of the following values:
    • NONE - don't notify the user when a new authentication method is added.
    • EMAIL_THEN_SMS - notify the user by email. If there is no email address in the user profile, notify the user by SMS. If there is no phone number either, don't notify the user.
    • SMS_THEN_EMAIL - notify the user by SMS. If there is no phone number in the user profile, notify the user by email. If there is no email address either, don't notify the user.
    If the parameter is not provided, the default value is EMAIL_THEN_SMS.
    notificationsPolicy.id String Optional Mutable If you want the MFA policy to use a specific notification policy rather than just using the default notification policy, use notificationsPolicy.id to specify the ID of the notification policy that should be used.
    rememberMe Object Optional Mutable Object used to specify that the MFA policy should include a "remember me" option so that users do not have to authenticate when accessing applications from a device they have used already.
    rememberMe.web Object Optional Mutable Contains the "remember me" settings for accessing applications from a browser.
    rememberMe.web.enabled Boolean Optional Mutable Set to true if you want the MFA policy to include a "remember me" option.
    rememberMe.web.lifeTime Object Optional Mutable Used to define the period during which users will not have to authenticate if they are accessing applications from a device they have used before. The "remember me" period can be anywhere from 1 hour to 90 days.
    rememberMe.web.lifeTime.timeUnit String Optional Mutable The time unit to use for the "remember me" period. Can be HOURS or DAYS.
    rememberMe.web.lifeTime.duration Integer Optional Mutable Used in conjunction with lifeTime.timeUnit to define the "remember me" period.
    sms Object Required Mutable SMS device authentication policy settings. Offline device (SMS, voice, email, WhatsApp) authentication policy data model
    totp Object Required Mutable TOTP device authentication policy settings. TOTP authentication policy data model
    updatedAt Date N/A Read-only When the resource was last updated.
    voice Object Required Mutable Voice device authentication policy settings. Offline device (SMS, voice, email, WhatsApp) authentication policy data model
    whatsApp Object Optional Mutable Contains the settings for using WhatsApp as an authentication method. Offline device (SMS, voice, email, WhatsApp) authentication policy data model

    FIDO device authentication policy data model

    All of the fields in the table below should be enclosed in the fido2 object, for example:

    "fido2" : {
    "enabled" : true,
    "pairingDisabled" : false
}
    Property Type Required? Mutable? Description
    enabled Boolean Required Mutable Whether the authentication method is enabled or disabled in the policy.
    failure Object Optional Mutable Contains the definitions for the maximum number of times authentication can fail before user is blocked temporarily, and how long the user should be blocked.
    failure.coolDown.duration Integer Optional Mutable Used in conjunction with failure.coolDown.timeUnit to specify how long the user should be blocked after reaching the maximum number of failures, before they can try authenticating again. Minimum period is two minutes, maximum is 30 minutes.
    failure.coolDown.timeUnit String Optional Mutable The units to use for failure.coolDown.duration. Can be SECONDS or MINUTES.
    failure.count Integer Optional Mutable The maximum number of times that authentication can fail before user is blocked for the specified period. Minimum is 1, maximum is 7.
    fido2PolicyId String Optional Mutable The ID of the specific FIDO policy that should be used. If this parameter is not provided, the default FIDO policy is used.
    pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.
    promptForNicknameOnPairing Boolean Optional Mutable Set to true if you want to allow users to provide nicknames for devices during pairing.

    Offline device (SMS, voice, email, WhatsApp) authentication policy data model

    Property Type Required? Mutable? Description
    enabled Boolean Required Mutable Whether the device is enabled or disabled in the policy.
    otp.failure.coolDown.duration Integer Required Mutable The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 0, maximum is 30, and the default is 0. Note that when using the "onetime authentication" feature, the user is not blocked after the maximum number of failures even if you specified a block duration.
    otp.failure.coolDown.timeUnit String Required Mutable The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.
    otp.failure.count Integer Required Mutable The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.
    otp.lifetime.duration Integer Required Mutable The duration (number of time units) that the passcode is valid before it expires. The minimum value is 1, maximum is 7, and the default is 3.
    otp.lifetime.timeUnit String Required Mutable The type of time unit for otp.lifetime.duration. Valid values are MINUTES and SECONDS.
    otp.otpLength Integer Optional Mutable Used to specify the length of the OTP that is shown to users. Minimum length is 6 digits and maximum is 10 digits. If the parameter is not provided, the default is 6 digits.
    pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.
    promptForNicknameOnPairing Boolean Optional Mutable Set to true if you want to allow users to provide nicknames for devices during pairing.

    Mobile device authentication policy data model

    All of the fields in the table below should be enclosed in the mobile object, for example:

    "mobile": {
    "enabled": true,
    "otp": {
        "failure": {
            "count": 3,
            "coolDown": {
                "duration": 2,
                "timeUnit": "MINUTES"
            }
        }
    },
    "applications": [
        {
            "id": "{{appID}}",
            "push": {
                "enabled": true,
                "numberMatching": {
                    "enabled": true
                }
            },
            "otp": {
                "enabled": true
            },
            "pushTimeout": {
                "duration" : 120,
                "timeUnit" : "SECONDS"
            },
            "pushLimit": {
                "count": 4,
                "timePeriod": {
                    "duration": 10,
                    "timeUnit": "MINUTES"
                },
                "lockDuration": {
                    "duration": 30,
                    "timeUnit": "MINUTES"
                }
            },
            "deviceAuthorization": {
                "enabled": true,
                "extraVerification": "permissive"
            },
            "autoEnrollment": {
                "enabled": true
            },
            "pairingKeyLifetime": {
                "duration": 40,
                "timeUnit": "HOURS"
            },
            "integrityDetection": "permissive"
        }
    ]
}
    Property Type Required? Mutable? Description
    applications[].autoEnrollment.enabled Boolean Required Mutable Set to true if you want the application to allow Auto Enrollment. Auto Enrollment means that the user can authenticate for the first time from an unpaired device, and the successful authentication will result in the pairing of the device for MFA.
    applications[].deviceAuthorization.enabled Boolean Required Mutable Specifies the enabled or disabled state of automatic MFA for native devices paired with the user, for the specified application.
    applications[].deviceAuthorization.extraVerification String Required Mutable Specifies the level of further verification when deviceAuthorization is enabled. The PingOne platform performs an extra verification check by sending a “silent” push notification to the customer native application, and receives a confirmation in return.
    extraVerification can be one of the following levels:
    • disabled (default): The PingOne platform does not perform the extra verification check.
    • permissive: The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the native app, the MFA step is treated as successfully completed.
    • restrictive: The PingOne platform performs the extra verification check.The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the native app, the MFA step is treated as failed.
    applications[].id String Required Immutable The application's UUID.
    applications[].integrityDetection String Required Mutable Controls how authentication or registration attempts should proceed if a device integrity check does not receive a response. Set the value to permissive if you want to allow the process to continue. Set the value to restrictive if you want to block the user in such situations.
    applications[].otp.enabled Boolean Required Mutable Specifies whether OTP authentication is enabled or disabled for the policy.
    applications[].pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant application. You can use this option if you want to phase out an existing mobile application but want to allow users to continue using the application for authentication for existing devices.
    applications[].pairingKeyLifetime.duration Integer Optional Mutable The amount of time an issued pairing key can be used until it expires. Minimum is 1 minute and maximum is 48 hours. If this parameter is not provided, the duration is set to 10 minutes.
    applications[].pairingKeyLifetime.timeUnit String Optional Mutable The time unit for the pairingKeyLifetime.duration parameter. The possible values are MINUTES and HOURS.
    applications[].push.enabled Boolean Required Mutable Specifies whether push notification is enabled or disabled for the policy.
    applications[].push.numberMatching.enabled Boolean Optional Mutable Set to true if you want the mobile push to require the user to match a number that they were shown when requesting access. To specify how the matching should be carried out, see the numberMatching.type parameter in the Applications OIDC settings data model.
    applications[].pushLimit.count Integer Optional Mutable The number of consecutive push notifications that can be ignored or rejected by a user within a defined period before push notifications are blocked for the application. The minimum value is 1 and the maximum value is 50. If this parameter is not provided, the default value is 5.
    applications[].pushLimit.lockDuration.duration Integer Optional Mutable The length of time that push notifications should be blocked for the application if the defined limit has been reached. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 30 minutes.
    applications[].pushLimit.lockDuration.timeUnit String Optional Mutable The time unit for the pushLimit.lockDuration.duration parameter. The valid values are MINUTES and SECONDS.
    applications[].pushLimit.timePeriod.duration Integer Optional Mutable The time period in which the push notifications are counted towards the defined limit. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 10 minutes.
    applications[].pushLimit.timePeriod.timeUnit String Optional Mutable The time unit for the pushLimit.timePeriod.duration parameter. The valid values are MINUTES and SECONDS.
    applications[].pushTimeout.duration Integer Optional Mutable The amount of time a user has to respond to a push notification before it expires. Minimum is 40 seconds and maximum is 150 seconds. If this parameter is not provided, the duration is set to 40 seconds.
    applications[].pushTimeout.timeUnit String Optional Mutable The time unit for the pushTimeout.duration parameter. Currently, the only permitted value is SECONDS.
    enabled Boolean Required Mutable Whether the device is enabled or disabled in the policy.
    otp.failure.coolDown.duration Integer Required Mutable The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 2, maximum is 30, and the default is 2. Note that when using the "onetime authentication" feature, the user is not blocked after the maximum number of failures even if you specified a block duration.
    otp.failure.coolDown.timeUnit String Required Mutable The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.
    otp.failure.count Integer Required Mutable The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.
    promptForNicknameOnPairing Boolean Optional Mutable Set to true if you want to allow users to provide nicknames for devices during pairing.

    TOTP device authentication policy data model

    Property Type Required? Mutable? Description
    enabled Boolean Required Mutable Whether the device is enabled or disabled in the policy.
    otp.failure.coolDown.duration Integer Required Mutable The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 2, maximum is 30, and the default is 2.
    otp.failure.coolDown.timeUnit String Required Mutable The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.
    otp.failure.count Integer Required Mutable The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.
    pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.
    promptForNicknameOnPairing Boolean Optional Mutable Set to true if you want to allow users to provide nicknames for devices during pairing.
    uriParameters Object Optional Mutable Object that you can use to provide key:value pairs for otpauth URI parameters. For example, if you provide a value for the issuer parameter, then authenticators that support that parameter will display the text you specify together with the OTP (in addition to the username). This can help users recognize which application the OTP is for. If you intend on using the same MFA policy for multiple applications, choose a name that reflects the group of applications.

    PLATFORM and SECURITY_KEY device authentication policy data model (deprecated, replaced by FIDO device)

    Property Type Required? Mutable? Description
    enabled Boolean N/A Read-only Whether the device is enabled or disabled in the policy.
    fidoPolicyId String N/A Read-only The FIDO policy UUID. This property can be null. When null, the environment's default FIDO Policy is used.

    Policy migration data model

    Used with the deviceAuthenticationPolicies endpoint and content type: application/vnd.pingidentity.deviceAuthenticationPolicy.fido2.migrate+json for batch conversion of device authentication policies associated with the previous FIDO policy format (device authentication policies that have FIDO Biometrics or Security Key enabled).

    Property Type Required? Mutable? Description
    migrationData Array Optional Immutable List of the objects that must be migrated.
    migrationData[].deviceAuthenticationPolicyId String Required Immutable The UUID of the device authentication policy to migrate. Required if you are providing the migrationData object.
    migrationData[].fido2PolicyId String Optional Immutable The UUID of the enhanced FIDO policy to associate with the device authentication policy. If this parameter is not provided, the default FIDO policy is used.

    Create Device Authentication Policy

    Read Device Authentication Policies

    Read One Device Authentication Policy

    Update Device Authentication Policy

    Delete Device Authentication Policy

    Migrate Device Authentication Policies

    Reporting

    You can use the reporting capability to generate reports containing user and MFA device details, using a number of device-related filters.

    For example, you can generate a report listing all email devices or a report containing all of the devices whose phone number starts with a certain country code.

    You can use synchronous requests to get back the matching data as entries in the JSON response or use asynchronous requests to have the data provided in a CSV or JSON file. Note that when using the synchronous approach, you may have to make multiple requests if there is a large amount of data.

    The request for generating reports uses the dataExplorations endpoint:

    https://{{apiPath}}/v1/environments/{{envId}}/dataExplorations

    MFA reports data model

    Property Type Required? Mutable? Description
    dataExplorationTemplate.id String Required Immutable The ID of the report template that should serve as the base for the report. Currently, the only supported value is db632bfd-7054-4bde-b108-a384aac2d513
    deliverAs String Optional Immutable How the results should be returned. The valid values are ENTRIES (get the results as a collection of entries in the response) and ASYNC_FILE (get the results in a CSV or JSON file). If the parameter is not included, ENTRIES is used.
    fields[] Array Optional Immutable The fields you want to include in the report. Array of name-value objects, where the name is always "name", for example, "fields":[{"name":"username"},{"name":"phone"}]. The values that can be included are: userId, environmentId, populationId, username, givenName, familyName, mfaEnabled, userCreatedAt, userUpdatedAt, deviceId, deviceOrder, deviceNickname, deviceType, deviceStatus, deviceIntegrityStateCompromised, deviceIntegrityStateReason, deviceIntegrityStateTimestamp, deviceIntegrityStateAdvice, phone, extension, email, deviceBlocked, blockedAt, deviceLocked, lockExpiration, fidoBackupEligibility, fidoBackupState, fidoUserVerification, sdkVersion, manufacturer, deviceName, modelName, osType, osVersion, appId, appVersion, mobileUnitId, installedApplicationId, rpId, deviceCreatedAt, deviceUpdatedAt, lastDeviceTrxTime
    Note that if you do not include the fields parameter, the report will include all of the fields available.
    filter String Optional Immutable You can filter the results by: email, phone, deviceType, userId, or mfaEnabled. The filters are used with the operators eq and sw. eq requires an exact match (including case-sensitivity). sw ("starts with") provides greater flexibility by matching only part of the string and performing a check that is not case-sensitive. The sw option can ony be used with the filters email and phone. When using the deviceType filter, you can use any of the values listed for type in the "Device properties" table under MFA devices.
    Examples: "filter": "(deviceType eq \"EMAIL\")", "filter": "(phone sw \"+972\")", "filter": "(mfaEnabled eq \"true\")"
    If you do not include the filter parameter, the report will include all users and their devices.
    sync String Optional Immutable Set to "true" if you are using the expand query parameter.

    Getting the report results

    You can receive the report data as entries in the JSON response or as a file (CSV or JSON).

    There are a number of ways you can get the report results. The recommended approaches for the most common scenarios are as follows:

    • For cases where you anticipate a fairly small number of records in the results:

      • Run a POST request using the expand query parameter. This will create the dataExplorations object and also return the results as entries in the response. {{apiPath}}/environments/{{envID}}/dataExplorations?expand=entries

        For more information on the use of the expand query parameter, see "Link expansion" under Conventions.

    • For cases where you expect a large number of records, but would like to receive them as entries in the body of the response:

      1. Run a POST request to create the dataExplorations object.

      2. Run a GET request with /entries in the URL: {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/entries

      3. If there are too many results to include in one response, the _links section in the response will include a next object. Follow the next link, then using the same access token, run another GET request using the the next link as the URL.

      4. Continue until the response no longer includes a next object.

        For more information on pagination, see Paging, ordering, and filtering collections.

    • For cases where you want to receive the results as a file:

      1. Run the request to create a report and get the results as a file: POST {{apiPath}}/environments/{{envID}}/dataExplorations. In the body of the request, make sure that deliverAs is set to ASYNC_FILE.
      2. The response to the report creation request will include a status field whose value is IN_PROGRESS.
      3. Run the polling request GET {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/, using the ID that was returned when you created the report, until the status field in the response equals SUCCESS.
      4. When the response contains the status SUCCESS, it will also include a link for downloading a zipped csv file, a link for downloading a zipped JSON file, and a password for opening the zip files. Use this information to download and unzip the report.
      5. The report itself is cached for two hours, but the links are good for only five minutes.
      6. If more than five minutes has elapsed from the time of the request that returned the links, get updated links by again running the request GET {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/ using the ID that was returned when you created the report.
      7. If more than two hours has elapsed since the report was created, run the report creation request again.

    Create report of SMS devices - entries in response

    Get report results - entries in response

    Create report of MFA-enabled devices - results in file

    Get report results - results in file - polling

    MFA Settings

    The MFA settings endpoint supports operations to read, update, and reset the PingOne MFA settings associated with a specified environment. A PUT request lets you manage the maximum number of allowed devices for pairing, and it lets you set the device selection option. A successful DELETE operation resets the MFA settings to the default.

    Maximum allowed devices

    The MFA settings property pairing.maxAllowedDevices defines the maximum number of paired MFA devices each user within an environment can have. This can be any number up to 15. The default value is 5. You can update the setting with GET {{apiPath}}/environments/{{envID}}/mfaSettings and reset the setting to its default with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

    If the maxAllowedDevices value is decreased below the number of paired devices a user currently has, the user's existing paired devices remain. After a paired device is deleted though, the user cannot replace it with a new one. This remains true until the number of existing paired devices is below the current value for maxAllowedDevices.

    If the maxAllowedDevices limit is reached and the user attempts to create a new device, an error similar to the following is returned.

    400 BAD REQUEST
{
  "id": "<errorId>",
  "code": "REQUEST_FAILED",
  "message": "The request could not be completed. There was an issue processing the request.",
  "details": [
    {
      "code": "LIMIT_EXCEEDED",
      "message": "Maximum allowed devices has been reached",
      "innerError": {
        "maximumAllowed": 5
      }
    }
  ]
}

    Account lockout

    The MFA settings property lockout.failureCount and lockout.durationSeconds defines the maximum number of incorrect MFA authorization actions a user can attempt (such as entering an incorrect OTP or denying a push confirmation on a native device) before the account is locked. The lockout.durationSeconds defines the amount of time after the lockout.failureCount value is exceeded to keep the account in a locked state. You can update the setting with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

    For more information about account lockout, see User Accounts.

    MFA settings data model

    Property Type Required? Mutable? Description
    lockout Object Optional Mutable Contains information about the MFA policy lockout settings.
    lockout.failureCount Integer Optional Mutable The maximum number of incorrect authentication attempts before the account is locked.
    lockout.durationSeconds Integer Optional Mutable The number of seconds to keep the account in a locked state.
    pairing Object Optional Mutable Contains information about the MFA policy device pairing settings.
    pairing.maxAllowedDevices Integer Optional Mutable The maximum number of MFA devices each user can have. This can be any number up to 15. The default value is 5. All devices that are Active or Blocked are subject to this limit.
    pairing.pairingKeyFormat String Optional Mutable The type of pairing key issued. The valid values are NUMERIC (12-digit key) and ALPHANUMERIC (16-character alphanumeric key).
    phoneExtensions Object Optional Mutable Contains settings for phone extension support.
    phoneExtensions.enabled Boolean Optional Mutable Set to true to allow one-time passwords to be delivered via voice to phone numbers that include extensions. Set to false to disable support for phone numbers with extensions. By default, support for extensions is disabled.
    updatedAt Date N/A Read-only When the resource was last updated.
    users Object Optional Mutable Contains information about the default settings for new users.
    users.mfaEnabled Boolean Optional Mutable Set mfaEnabled to true if you want MFA to be enabled by default for new users.

    Response codes

    Code Message
    200 Successful operation.
    400 The request could not be completed.
    401 You do not have access to this resource.
    404 The requested resource was not found.

    Read MFA Settings

    Update MFA Settings

    Reset MFA Settings

    OATH Tokens

    You can use the PingOne API for various oath token management actions, including creating tokens, revoking tokens, and resyncing tokens.

    OATH token data model

    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The date the token was added to the environment.
    environment.id String N/A Read-only The ID of the environment the token is associated with.
    hashAlgorithm String Optional Immutable The algorithm used by the cryptographic hash function to generate OTPs. Can be any of the following values: HmacSHA1, HmacSHA256, HmacSHA512. If not provided, HmacSHA1 is used as the default value. Currently for HOTP tokens, only HmacSHA1 is supported, so this parameter is really only relevant for TOTP tokens.
    hotp Object Optional Immutable Object containing fields that are relevant only for HOTP tokens.
    hotp.counter Integer Optional Immutable The counter used by the HOTP token to generate OTPs. If not provided, 0 is used as the default value.
    id String N/A Read-only The OATH token's unique identifier.
    otpLength Integer Required Immutable Length of the OTPs generated - can be 6 or 8
    rowNumber Integer Optional Immutable When creating OATH tokens with data that originated in a seed file, rowNumber can be used to indicate the row where the data for the token was located in the file.
    secret String Required Immutable The OATH token's secret key. Can be up to 200 characters and must be a hexadecimal value. Used only as an input parameter, does not appear in any responses.
    serialNumber String Required Immutable The OATH token's serial number. Can be up to 50 characters and all characters must be alphanumeric.
    totp Object Required Immutable Object containing fields that are relevant only for TOTP tokens.
    totp.drift Integer N/A Read-only Difference between the token's time and the server's time, expressed in time steps. A positive value indicates that the token's time is ahead.
    totp.timeStep Integer Required Immutable Interval at which the OTP is refreshed - PingOne supports 30 seconds and 60 seconds.
    type String Required Immutable Possible values are HOTP and TOTP.
    updatedAt Date N/A Read-only The date the token was last updated.
    _embedded.devices Array N/A Read-only Array of devices associated with an OATH token.
    _embedded.devices.id String N/A Read-only ID of device associated with an OATH token.
    _embedded.devices.userId String N/A Read-only ID of user for a device associated with an OATH token.
    _embedded.oathTokens Array N/A Read-only Name of the array of tokens returned when all tokens are requested.

    OATH token batch creation data model

    These properties are relevant only for batch creation of tokens.

    Property Type Required? Mutable? Description
    reason String N/A Read-only If the job status is FAILED, provides the reason for the failure.
    result.created Integer N/A Read-only The number of tokens created.
    result.duplicates Object N/A Read-only Contains information about tokens whose creation was requested but were skipped because they already exist in the environment.
    result.duplicates.maskedSecret String N/A Read-only The secret for the OATH token, partially-hidden.
    result.duplicates.rowNumber Integer N/A Read-only The number of the row where the duplicate token was in the file whose content was imported.
    result.duplicates.serialNumber String N/A Read-only The serial number of the duplicate token.
    status String N/A Read-only The status of the job. Can be PENDING, IN_PROGRESS, FAILED, or DONE.
    tokens Array Required Immutable Name of the array of tokens provided for creation. Each item in the array should include the same information you would include to create a single token, for example, serial number, as described in the OATH token data model table.
    type String Required Immutable The type of job to run. For creation of tokens, set to 'CREATE_OATH_TOKENS'. Should not be confused with the type parameter used within each token in the array provided to indicate the type of token to create - TOTP or HOTP.

    OATH token batch revoking data model

    These properties are relevant only for batch revoking of tokens.

    Property Type Required? Mutable? Description
    forceUnpair Boolean Optional Immutable By default, revoke jobs revoke only unassigned tokens. Set forceUnpair to true if you want tokens to be revoked even if they are currently associated with a user. The association (device) will be removed before the token is revoked. When forceUnpair is not used, the response includes an array of tokens that were not revoked due to their association with a user.
    reason String N/A Read-only If the job status is FAILED, provides the reason for the failure.
    result.revoked Integer N/A Read-only The number of tokens revoked.
    result.unrevoked Array N/A Read-only Array of objects that contain information about the tokens that were not revoked because they are associated with a user.
    result.unrevoked[].devices[].id String N/A Read-only ID of device associated with the token that was not revoked.
    result.unrevoked[].devices[].user.id String N/A Read-only ID of user whose device is associated with the token that was not revoked.
    result.unrevoked[].devices Array N/A Read-only Array of devices associated with the token that was not revoked.
    result.unrevoked[].id String N/A Read-only ID of the token that was not revoked.
    status String N/A Read-only The status of the job. Can be PENDING, IN_PROGRESS, FAILED, or DONE.
    tokenIds Array Required Immutable Name of the array of tokens provided for revoking. Each element in the array should be the ID of the token to revoke. The maximum number of token IDs you can include in a batch revoke is 1000.
    type String Required Immutable The type of job to run. For revoking of tokens, set to 'REVOKE_OATH_TOKENS'.

    OATH token resync data model

    These properties are relevant only for resyncing tokens.

    Property Type Required? Mutable? Description
    otps Array Required Immutable Required for resync requests. array of two OTPs for the token, used to calculate the resync. The two OTPs can be provided in a single request or in two separate requests.

    Create OATH token (TOTP)

    Create OATH token (HOTP)

    Create multiple OATH tokens

    Check status of OATH token creation job

    Retrieve all OATH tokens

    Retrieve OATH token by ID

    Retrieve OATH token by serial number

    Revoke OATH token

    Revoke multiple OATH tokens

    Check status of OATH token revoke job

    Resync OATH token

    Resync OATH token paired with user

    FIDO Policies

    FIDO policies

    FIDO policies allow you to fine-tune the use of FIDO2 authentication in authentication flows, for example, by limiting authentication to specific types of FIDO2 devices.

    An endpoint (fidoDevicesMetadata) is also provided for reading information from the device metadata table stored by PingOne, and for adding or removing custom devices.

    FIDO policies data model

    Property Type Required? Mutable? Description
    aggregateDevices Boolean Optional Mutable By default, when the user is presented with a list of available authentication methods, each paired FIDO2 device is displayed separately. If you prefer to have only one generic FIDO2 option displayed in the list, set aggregateDevices to true. The text displayed for the single option will be the value of the parameter deviceDisplayName.
    attestationRequirements String Required Mutable Set to DIRECT if you want to require some sort of attestation. Set to NONE if you don't want to require attestation. If you set attestationRequirements to NONE, you should also set mdsAuthenticatorsRequirements.option to NONE.
    authenticatorAttachment String Required Mutable Used to control the type of authenticators that are allowed. Can be one of the following values:
    • PLATFORM - only allow the use of FIDO device authenticators that contain an internal authenticator (such as a face or fingerprint scanner)
    • CROSS_PLATFORM - allow use of cross-platform authenticators, which are external to the accessing device (such as a security key)
    • BOTH - allow both categories of authenticators
    backupEligibility Object Required Mutable Used to control whether users should be allowed to register and authenticate with a device that uses cloud-synced credentials, such as a passkey.
    backupEligibility.allow Boolean Required Mutable Set to true if you want to let users register and authenticate with a device that uses cloud-synced credentials. Set to false if you don't want to allow this.
    backupEligibility.enforceDuringAuthentication Boolean Required Mutable Set to true if you want the backup eligibility of the device to be checked again at each authentication attempt and not just once during registration. Set to false to have it checked only at registration.
    default Boolean Optional Mutable Whether this policy should serve as the default FIDO policy.
    description String Optional Mutable Description of the FIDO policy.
    deviceAuthenticationPolicies Array N/A Read-only The device authentication policies that use the relevant FIDO policy. If you include the parameter expand=deviceAuthenticationPolicies in the URL of the request, this array is included in the response when reading FIDO policies. Each object in the array contains the ID and the name of the device authentication policy.
    deviceDisplayName String Required Mutable The name to display for FIDO2 devices in registration and authentication windows. Can be up to 100 characters. If you want to use translatable text, you can use any of the keys listed on the FIDO Policy page of the Self-Service module and the Sign On Policy module. The value of the parameter should include only the part of the key name that comes after the module name, for example, fidoPolicy.deviceDisplayName01 or fidoPolicy.deviceDisplayName07. See the pages in the UI for the full list of keys. For more information on translatable keys, see Modifying translatable keys in the PingOne documentation. If users have more than one paired FIDO2 device, they can differentiate between them by setting a nickname for each one.
    discoverableCredentials String Required Mutable Use this field to specify when registered users can authenticate without providing credentials. The possible values are:
    • DISCOURAGED - discoverable credentials are not used, even when supported by the FIDO device. In cases where use of discoverable credentials is required by the FIDO device itself, this setting does not override the device setting.
    • REQUIRED - require the use of discoverable credentials. This option is required for usernameless authentication.
    • PREFERRED - use discoverable credentials where possible.
    mdsAuthenticatorsRequirements Object Required Mutable Used to specify whether attestation is requested from the authenticator, and whether this information is used to restrict authenticator usage.
    mdsAuthenticatorsRequirements.allowedAuthenticators Array Required Mutable If you set mdsAuthenticatorsRequirements.option to SPECIFIC, use this array to specify the authenticators that you want to allow.
    mdsAuthenticatorsRequirements.allowedAuthenticators.id String Required Mutable The mdsIdentitfer of the authenticator to allow.
    mdsAuthenticatorsRequirements.enforceDuringAuthentication Boolean Required Mutable Set to true if you want the device characteristics related to attestation to be checked again at each authentication attempt and not just once during registration. Set to false to have them checked only at registration.
    mdsAuthenticatorsRequirements.option String Required Mutable Use option to specify the types of devices you want to allow on the basis of the attestation provided. Can be one of the following values:
    • NONE - do not request attestation, allow all FIDO devices
    • AUDIT_ONLY - attestation is requested and the information is used for logging purposes, but the information is not used for filtering authenticators
    • GLOBAL - allow use of all FIDO authenticators listed in the Global Authenticators table.
    • CERTIFIED - allow only FIDO Certified authenticators
    • SPECIFIC - allow only the authenticators specified with the mdsAuthenticatorsRequirements.allowedAuthenticators parameter.
    name String Required Mutable The name to use for the FIDO policy. Can be up to 256 characters.
    relyingPartyId String Required Mutable The ID of the relying party. The value should be a domain name, such as example.com (in lower-case characters).
    userDisplayNameAttributes Object Required Mutable Used to specify the string associated with the users's account that is displayed during registration and authentication.
    userDisplayNameAttributes.attributes Array Required Mutable List of strings associated with the users's account that can be displayed during registration and authentication. Each object in the array is a name:value pair where the first part is "name" and the second is the name of the user attribute, for example, {"name": "username"}, {"name": "email"}. If you want to use the "name" attribute for the user, you must also specify the "subAttributes", which can be either the "given" and "family" user attributes or the "formatted" user attribute. For example, {"name": “name”, “subAttributes”:[{“name”: “given”}, {“name”: “family”}]}, {"name": "email"} or {"name": “name”, “subAttributes”:[{“name”: “formatted”}]}, {"name": "email"}.
    • The content of the list should reflect the preferred order.
    • If the first attribute is empty for the user, PingOne will continue through the list until a non-empty attribute is found.
    • You can specify any user attribute (including custom attributes) that meet the following criteria: attribute type must be String, validation cannot be set to enumerated values.
    • The array must contain the user attribute "username" - to ensure that there is at least one non-empty attribute.
    • You can have a maximum of six user attributes in the list.
    userVerification Object Required Mutable Used to control whether the user must perform a gesture (such as a public key credential, fingerprint scan, or a PIN code) when registering or authenticating with their FIDO device.
    userVerification.enforceDuringAuthentication Boolean Required Mutable Set to true if you want the device characteristics related to user verification to be checked again at each authentication attempt and not just once during registration. Set to false to have them checked only at registration.
    userVerification.option String Required Mutable Can be one of the following values:
    • REQUIRED - only FIDO devices supporting user verification can be used
    • DISCOURAGED - user verification is not required, even when supported by the FIDO device. In cases where user verification is required by the FIDO device itself, this setting does not override the device setting.
    • PREFERRED - user verification is required if the user's FIDO device supports it, but is not required if the user's device does not support it.
    For usernameless flows, only FIDO devices supporting user verification can be used, regardless of the value you set for userVerification.option.

    Additional information returned in responses

    • id - the ID assigned to the policy
    • createdAt
    • updatedAt
    • _embedded.deviceAuthenticationPolicies - array of the device authentication polices that the FIDO policy is used by. Each object in the array consists of the ID of the device authentication policy and the name of the device authentication policy. Returned only if the query includes the parameter expand=deviceAuthenticationPolicies.

    FIDO device metadata

    PingOne maintains a global authenticator table, which presents metadata for indvidual authenticators. This includes both authenticators that are represented in the FIDO Alliance Metadata Service (MDS), and custom authenticator data that you add to the table via the UI or the API.

    The endpoints provided for FIDO device metadata allow you to:

    • Retrieve the basic metadata for all of the authenticators in the table
    • Retrieve detailed metadata for a specific authenticator from the table
    • Add metadata for custom authenticators
    • Delete from the table a custom authenticator that you added

    Adding a custom authenticator

    When you use the fidoDevicesMetadata endpoint to add a custom authenticator to the global authenticator table, the data included in the request should comform with the Metadata Statement Format provided by the FIDO Alliance.

    Before adding an authenticator, using JSON data provided by a manufacturer, verify that it conforms to the following details expected by the PingOne API:

    • The metadata outlined in the standard should be enclosed in an object called metadataStatement.
    • The metadataStatement should be enclosed in an object that also includes the relevant key identifier: the attestationCertificateKeyIdentifiers array for devices conforming with the U2F protocol, and the aaguid field for devices conforming with the FIDO2 protocol.
    Sample body for request - U2F device
    {
    "attestationCertificateKeyIdentifiers": [
        "31116a647069d1493f58fc5b54e5449e2a52d43e"
    ],
    "metadataStatement": {
        "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
        "attestationCertificateKeyIdentifiers": [
            "31116a647069d1493f58fc5b54e5449e2a52d43e"
        ],
        "description": "Yubikey Edge",
        "authenticatorVersion": 1,
        "protocolFamily": "u2f",
        "schema": 3,
        "upv": [
            {
                "major": 1,
                "minor": 1
            }
        ],
        "authenticationAlgorithms": [
            "secp256r1_ecdsa_sha256_raw"
        ],
        "publicKeyAlgAndEncodings": [
            "ecc_x962_raw"
        ],
        "attestationTypes": [
            "basic_full"
        ],
        "userVerificationDetails": [
            [
                {
                    "userVerificationMethod": "presence_internal"
                }
            ]
        ],
        "keyProtection": [
            "hardware",
            "secure_element",
            "remote_handle"
        ],
        "isKeyRestricted": false,
        "isFreshUserVerificationRequired": false,
        "matcherProtection": [
            "on_chip"
        ],
        "cryptoStrength": 128,
        "attachmentHint": [
            "external",
            "wired"
        ],
        "attestationRootCertificates": [
            "MIIDHjCCAgagAwIBAgIEG0BT9zANBgkqhkiG9w0BAQsFADAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowLjEsMCoGA1UEAxMjWXViaWNvIFUyRiBSb290IENBIFNlcmlhbCA0NTcyMDA2MzEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC/jwYuhBVlqaiYWEMsrWFisgJ+PtM91eSrpI4TK7U53mwCIawSDHy8vUmk5N2KAj9abvT9NP5SMS1hQi3usxoYGonXQgfO6ZXyUA9a+KAkqdFnBnlyugSeCOep8EdZFfsaRFtMjkwz5Gcz2Py4vIYvCdMHPtwaz0bVuzneueIEz6TnQjE63Rdt2zbwnebwTG5ZybeWSwbzy+BJ34ZHcUhPAY89yJQXuE0IzMZFcEBbPNRbWECRKgjq//qT9nmDOFVlSRCt2wiqPSzluwn+v+suQEBsUjTGMEd25tKXXTkNW21wIWbxeSyUoTXwLvGS6xlwQSgNpk2qXYwf8iXg7VWZAgMBAAGjQjBAMB0GA1UdDgQWBBQgIvz0bNGJhjgpToksyKpP9xv9oDAPBgNVHRMECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjANBgkqhkiG9w0BAQsFAAOCAQEAjvjuOMDSa+JXFCLyBKsycXtBVZsJ4Ue3LbaEsPY4MYN/hIQ5ZM5p7EjfcnMG4CtYkNsfNHc0AhBLdq45rnT87q/6O3vUEtNMafbhU6kthX7Y+9XFN9NpmYxr+ekVY5xOxi8h9JDIgoMP4VB1uS0aunL1IGqrNooL9mmFnL2kLVVee6/VR6C5+KSTCMCWppMuJIZII2v9o4dkoZ8Y7QRjQlLfYzd3qGtKbw7xaF1UsG/5xUb/Btwb2X2g4InpiB/yt/3CpQXpiWX/K4mBvUKiGn05ZsqeY1gx4g0xLBqcU9psmyPzK+Vsgw2jeRQ5JlKDyqE0hebfC1tvFu0CCrJFcw=="
        ],
        "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAfCAYAAACGVs+MAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAHYYAAB2GAV2iE4EAAAbNSURBVFhHpVd7TNV1FD/3d59weQSIgS9AQAXcFLAQZi9fpeVz1tY/WTZr5Wxpc7W5knLa5jI3Z85srS2nM2sjtWwZS7IUH4H4xCnEQx4DAZF74V7us885v9/lInBvVJ/B4Pv9nu/5nu/5nvM556fzA/Qv0Hb/IrX3VFKPo45cnm4inUIWYwLFRmZQUuwjFG/N1iRHh1EZ0NRVRudqt1Bd+2nSKyS/Ohys0+lk3e/3kQ9qvD4ZUta4VVSUuY0eipyiThAfocoORVgDuuw3qKRiAd3rbcEtjTjYIof6WaHsCmzVPWCMx+cgh8tLqWMKaMWsUjLqo2RtJIQ0oOzmerpQu4esZgsONkGxH7d0kdvTT17s4OMU7VI8ZhjgGaM+Aq9iENu8Pif1udz07MwvKWf8GlVoCEY04PC5WdTaXYFbR8vNvL5+3Kgfb5xNMya9RamJiynaMlGTVtFlr6ba9u+pqnEX4uMuRRgjSYEhrN7utFFe6lqal7Nfkw5imAGHynPpbk8VmY0xstnptlFCVCYtzTuBN83QpMLjTtevdPzSUnJ7e8mkjxZ39fXbKDfldZqbvU+TUgGnBVF6fQ2iPHg4W16UWUwvzbk16sMZE+Pn0pvz7JSeuAyes8lcpCmaKuo/p+qWr2UcwIAHWrvP0YEzhXAtLAbssHhp7iGamvyijP8ryqrXUWX9XoowxyAufNBrp43POBFXZlkf8MDRiqcpyowAwpuz2x+fWvz/Dtde9smszygtcR6C1wbdzBl6Olq5WNYY4oGathJMrkTEx0jARSHAVs+5rYkQNXb+QgfPLsQ6gXyInsreQfmpm7RVFYfL86n1fiUOkYvShkUPxvbukzoy6K1ihM1ho3XzW6EvSfXA+dpiWGaWd+doXzLzmGwKYFLCAsRAlPBAhMlCFXU7tBUVPr8HgVcJHWq+F00plr+DMTdrP4zvxY11kNMhxT+SeTGg+d4V5LQJityUGJNB8VFZsjgYBZM/II/XCTkj0qyDOpF2AVQ17CIjUp/DnT1UkL5F5gdj+sS1wg1gE3gigm60fCXzSnPXbyAPbIXv+IDpE16ThaHIS9skyhlmME5F3cfqAKhq2C0E5PH1gYaXaLPDkZG0HDJOnKWHp51I0z5SOux8e1WAuZzdHQrTkp8TmjXoI+la0wGZszubqbO3ifQ6A/W7vVSYsV3mR0JKwkKc4WHiBkmR8I3CCgI87oOL4qzT5P+RUJBejEOgAPK8hYPzatM+eITp2IO9yTQmeromPRxx1qxAcsile/ubSeEbcWQGYECghcLY2HyKjogjH25hMpjpUv1Ougli4eh2eRw0O32bJjkyuCgNzg0vzlYMSiSs0uoo4MG7hMOjCEaX1yFE0nSvjBzuTnEpK86Z8IoqFAIubw8kg9ArEaREWSZI+jH4Xbp6g9E9EnJT3oaRzDN+MUJBQDHn56a8oUmEBusOxBs/N5+tJEbPkAFDj8UGvOs/IWvcSglGBhvS7/FTYfpWGYdDY8fPAxWSA35sTC4p4+Lm4AaqIoPeQtfufK6Jh0ZhxlbsUXOSmXNifD5ZTAkyDofbbcclxnA8WNAqxCbRNykhXxQpaDw67fXUYbsiG0Khtv2oeIvh8rhQMYOcEAqXG/eI+zngOc5yxr8q82IAM1c/FLFOplqu5eFQXrMZzGcVCjYbLWG5I4BT1euRrlbxtNOtMitDDEhLXIIynAAvuOEWE3X3NdAft94VgaG42XIQt0ZX6PeCE/qQFe9rK6Hx7YU50KvH7fW4fS+q7KKBJxsggBX5pSAGh1jIrVh5zQ6w3RfaahBXm/aCbCZTjCUFUTyWZqW9p62MjJPXVqOrPgMO4Nv74Gkf+owftNVBDQnjFJqHSw17pXvhWW5KZqe/Q49N/USTCAVWoQXFIHBHXXe3FPrUDsuGDmtF/hHKTHpekxhiAOPI+SJq6S6HF4I9YWzkBJTo46iUMzWp8Pir/RiduLxKYsSksV8vLlOQvhGX2YlR0OBhBjC+u/gEcvY0ApK7Yk41NxjPSQnWFHTF66UrjgevB8Cu5a+l2vYSRPtuVDo73hhdMSHnUX7tTjsVZGxAl/WptiOIEQ1gnL29mX6/tR1tmlkYj8W4X+CSjWcUDGY1NpS/C7hSKqiMLM/l2QmSWZ73Ddz+gio8BCENYPQ46qnkzwXUbqvBkxjUQsWfZFgbuo3rAf+wN7jOO90+ynx4Pi3L+0nYL1SchDUgAP4gPV/7Id1q+1HShmuGkIqWRPgyxMFqP8HfjTnjXwY5bQfbJct6OIzKgMHotF/He1egsaxHSqG6wfdmQ5x8NyTFFqBcp2iSowHR3yk5+36hF7vXAAAAAElFTkSuQmCC"
    }
}
    Sample body for request - FIDO2 device
    {
    "aaguid": "e1a96183-5016-4f24-b55b-e3ae23614cc6",
    "metadataStatement": {
        "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
        "aaguid": "e1a96183-5016-4f24-b55b-e3ae23614cc6",
        "description": "ATKey.Pro CTAP2.0",
        "authenticatorVersion": 2,
        "protocolFamily": "fido2",
        "schema": 3,
        "upv": [
            {
                "major": 1,
                "minor": 0
            }
        ],
        "authenticationAlgorithms": [
            "secp256r1_ecdsa_sha256_raw"
        ],
        "publicKeyAlgAndEncodings": [
            "cose"
        ],
        "attestationTypes": [
            "basic_full"
        ],
        "userVerificationDetails": [
            [
                {
                    "userVerificationMethod": "fingerprint_internal",
                    "baDesc": {
                        "selfAttestedFRR": 0,
                        "selfAttestedFAR": 0,
                        "maxTemplates": 0,
                        "maxRetries": 0,
                        "blockSlowdown": 0
                    }
                },
                {
                    "userVerificationMethod": "presence_internal"
                },
                {
                    "userVerificationMethod": "passcode_internal"
                }
            ]
        ],
        "keyProtection": [
            "hardware"
        ],
        "isKeyRestricted": false,
        "isFreshUserVerificationRequired": true,
        "matcherProtection": [
            "on_chip"
        ],
        "attachmentHint": [
            "external"
        ],
        "attestationRootCertificates": [
            "MIIBzDCCAXGgAwIBAgIBATAKBggqhkjOPQQDAjBiMQswCQYDVQQGEwJTRTESMBAGA1UECgwJQVRLZXlDQTAwMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRswGQYDVQQDExJBdXRoZW50cmVuZCBDQSAwMDAwIBcNMTYwMjI2MDgxMTA2WhgPMjA1MDAyMjUwODExMDZaMGIxCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlBVEtleUNBMDAxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xGzAZBgNVBAMTEkF1dGhlbnRyZW5kIENBIDAwMDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAJcWqeCxga9KJbFO2TZdjcgrtZAgfi8TXKu+v5lcR5ceb5GJYxyoCjhueESL3ddmMIkpGyhsEEtfFUyBwsyFVCjFjAUMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwIDSQAwRgIhAPuVS4Pm2KFXdUMi5Pb/Xy+gCROOuRPZ6I57vWc0EvkBAiEA8aRCnXppAffCEOQBJ7vlgwiiHMXA2tpWX+ObvVKxXbM=",
            "MIIBzDCCAXGgAwIBAgIBATAKBggqhkjOPQQDAjBiMQswCQYDVQQGEwJTRTESMBAGA1UECgwJQVRLZXlDQTAwMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRswGQYDVQQDExJBdXRoZW50cmVuZCBDQSAwMDAwIBcNMTYwMjI2MDgxMTA2WhgPMjA1MDAyMjUwODExMDZaMGIxCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlBVEtleUNBMDAxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xGzAZBgNVBAMTEkF1dGhlbnRyZW5kIENBIDAwMDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAJcWqeCxga9KJbFO2TZdjcgrtZAgfi8TXKu+v5lcR5ceb5GJYxyoCjhueESL3ddmMIkpGyhsEEtfFUyBwsyFVCjFjAUMBIGA1UdEwEB/wQIMAYBAQECAQAwCgYIKoZIzj0EAwIDSQAwRgIhAMqIc/Qtr+jZbnrJB7g7W8r/DHmDe+IyFvzwpzdSrxEXAiEAtXcixZznhcDzlnIqFqkIJRGmvL9Yr6lVoP1ZkDeqmjk="
        ],
        "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAJYAAAA9CAIAAADAuAeYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0Ad5mH3gAABGuSURBVHhe7ZwJfBPV9sczS/Y03Rco3XcKBVwRBHkiT58LqxvCE3AtoIICBQTZ2gItUigtVGihKPoXAR+yyPLhARZZ1EdVoPoQpKW0BVq6Zc9klvxPMrfQliZNl7QPP/l+LnTmnDuTyfzuvefcm0kws9kscHEvg6O/Lu5ZUC/8z4BnNL8WYYSIt3Y7HGsIeH5M/M4stO/CNkjCswPHan/5HRf/r0jI6gz+45/t/fkatO/CNmggxXhwHLbMNGM20d1TaEaAWy4DwzG4Ev7aXNgH9cLCR8ZBL8TEIjPHyWLCcYLo+jQHpDPTtO7iFUxIcnqD38vP9t6WgXwubNNUQpFQQDODq88Schnv7mKoylunAu4nlZ4uCR2neUYKirJaPdrpcjidAW25cJgWJxVdPYQ2ohtf+l7FNS+85+lMCVmDkTOZOBPF0TSHbC6cTqdJqP/vle9k0af8Hjrp++BJZT+mph45XDiZTpPwYuICAhebWVbAmVmjoWSxa1beRXSOhPristoTx3GFDCMIjMAJhdv1TdtpjRa5XTiTzpHw8rSFBOmBYRirN3IUIyAwAU2XLs5EbhfOpBMkNJTdqD58hJBKYELpN/455cN9zRRNKOTlG75g9K55ntPpBAkvTV9MkAoBJmBYTVTWorDUObSxDoZTjjJeS3Z91OB0OiQhzMMN16uq9x3CZVJOb/AZMUKodPMYfL8iKp6jaFIuL1+/jaNMqLYL59AhCTGB4MrMFIIQwzbNqGJyV/D2yDULGGM9dETIaErTN/JGF06iQxJSlbeqdu63dEGD0XvIMGlIIG/3eeZvssgYmOALZfKyNfkczfB2F86gQxJeSUrDcEIAiSitjtmYiqxWIlfOZQxqgZBg62rL1my22lzrn06h/RJS1bVVn+8l5FLOSHkMHCSPi0QOK77jnpKFRppNDC5TlGVsZs2cddx10fm0X8KShRlmM2vpgib17SjYmLC0JMagwUjCVHmrYt1nyOqis2mnhHS96mb+LkIuMzOMcsADsqhQqqoaQuPtYrpV6/X4I9KgYAHLEVJZ+apc1zDqJNopYcmSdWYTDTknRpLG4rKTnv1/CB7yQ8jQ2+VM0OAzIY8yKq2AwHEhaaiouL7pS3Swi06lPRIyWv3N3O3WhzMsz0yZIc6RJCYSNi8EASkMVIBapFR+bcUn6HgXnUrzZ2egbz1SekLk78u7W+TSe0uvZX1Ckm5oH4HhMgnIBVsgKmegmqWgNFPXOyczMPEVtN8ShuLSMxFD7n52JjdvS0HBCYlYrKeopYsWRkU1SZ2akZyS+uefxUJSCNdSr6p/8IEH5ibNrqmpfStxuqe7u9FkHDjw4XemTd29Z++Or3bI5Qo7mbKJNvVLSJg1a2ZxcfGsOfO8Pb04M0eQRO7GHFTDNnq94d0ZM+FO4BheW1+/MSfb19feXW03JPrrMGaW5erUPV56wdrJGoC+JiKrvtwvEAlBQFws9h33pOWJwkZ3hzPRhj+uoJ02cuHChf3fHpDL5VqdbuZ77yBrSyTNnb8pb7NcJocrUqnU8fFxu3ZsBztFGffs3Rvg76/T6iRiCVj+vHxl7/4Dnh4eZtsaGg1GygRtURAeHn6hqEij1pAkWa9SjRk9+ul/PMnXscXWrZ/u3Pm1m9LNaKDuG9DfSfoBbZYQlIvdthrtNOVG/g5S5G5mWDLQIy5/FbJ2BiKxWCqXQWEFHMRWZL2LufPm5+bn+/j6gn5wo/sPSPj+u2O8C7qCVGo5A2c2w9nAIhTC6G6x2JEQw3GRxKI3kJaaMuXtRH8Pd5wkl6eltSohtCRPH2+RUKjRaFNSliCrE2hbLKQp09Xl60tXbLianFX+yd3pScO9YFm0YQWspatyr6Zml8KxGVts3rCOMW/+wo15+d5e3tb+p4qLir6tX4vo9LqayltVllJtp6jrVXz9cc+PVcjkLMeKxaLffv+9sLCQt7fI9q92lJVXCIVCiqL6D+j38EMPIYcTaJuEFRn5lxYsvvLhqouL5pEyS1t2BAiPdFXNHws/urJg1aVZc27tOYIcnceChR/lbMr18bHqp1ZHhoefKDiKfDaY9f7M2pqbZSWXym2XqhulX2zbig6AV5k3R1WngpdQSGXJKSuRtSXWZa9XKOTwxuvqVR8mzUFW59AGCSEKlmfkSWQBhETqHv5gwKtjkcMBwlLel7gFEQo3kcjvqvWj4E7si/MXfJSVs9HX1wdurlqtjouOPn2yAPlsI5FIPD09le7udoqHh4dCoUAHCATTp0/DMYzjOJFEeurMqeLiEuRoysFDhy/+cVkoEtE0HR0R8dRTrQy5HaQNEpZnfWaqrhIICcaoDkttU8syE2Jx0MwprFaNSUTac+dqDp3orNW2JUuTczZu8rPGP7VaA8lqwfF/I1+LYB1qPW++8ZpGq8NxTCgUp6V/jKxNWbs2SyaXwfVAPJ71wQxkdRoOS8iZyz7OJaQKs4mRBocFvPwMsjuERa+g2a8TCqWA4wiRvLMejlqyNGVt9nofH0v/02g08bGxJ+3GPwtm69W0l6SkOSajEWZikBvtP3CgtrYGORo4feaHs7/+AvMfhmEC/QNeGf8ycjgNRyUsz/vSWFGOCUnaoA5b0p6WJVQqA6e+wmo1mESs+qmw9vgZ5Ggvy9PSIeT4eFviH6T70VFRR44cRD7bgH4dkdDDXTl2zCiY8+E4TjPsuqwNyNHA2rWZoB8/JCQmvoWszsQhCSG/LFu50dIFaUYaGNRjyvPI0UaCkt7GYSoNHVEo4yNiO8AJyzUvX5m+Kn21l7cXTEmh//WOiz125JCd+cZtYBTlB9Kqqqpfz50v+u13O+X8+aKSq80D3sL583RaLXRESFi2/d+XEPCQQyAoKvr9u+9PSqVSlmXdPZSvTZmMHM7EIQmrtn6tLymB4Z81aEI+nIasbUfs49VzygssxBKpuP770/WnLXl5myITZBNKN7fs9TnpqzO8fX1APxNFxcfFHT64HybdqJJj5OZtGTDggUFDhw0aYrPcP3DQjPdnowMaCI8If2zoECNF4QShUqnzNm9BDoEgMysLjPyo/uqECfIu+YKYQ822dHmOUCI3M4w4oGfPt+2tkLVK0PxEHCbLHIeT0pJFa5HVYWRSacrytOQVK72t46fAbGYoU+7GHJiBoRqt0jCMKuQKH39/fz8/+GerBPj7QVaKDmjEgg/nqVUqzCyQK2Sb8pCEpdeuHThwSC6TQcoqkYindckoCrQuYeX2/frLlwUiEavXBs15gx/H2ge0BklPf/+JY1itHpdJ6o6eUJ0tcjwyWTTD8CPHjrkpFNAdeQtGEnOS5vMVHKKh1xuNhrq6OlV9fX1dnZ2i17XwQPPDDz2Y0LcPRZuEpLC8vGL3N9+AEcYGmmUgRmp1urGjR/n5+fGVnU3ry9w/9n3K+Oc1DOKMTDqw7CRpXZ1qkWNYCKn0gHgp7uU/8JLNzNBQWvFj9HBcJOSMlOcTg/sdzEcO28vcs5PmffHl9sZTNJPJRJtoyN1Bxprq6pRlS6ZPTUS+lrh542ZUXN+AHv56rW7UqJEbsjNPnjp17Ph3MDtENVqCppnIiPCXXnwB7Tdiz779r05+3c/P12g0xsXE7Nvzr9j4BMtXzDFMr9OdPHEsIjwCVXUyrcSP6/m76otOkQIvRqCOmZ9sRz/ALGAt39NnoDRZYGuGNCTQ78Wnb37+L0Iqu3XosOb8RbeEWORzDK1W2yc+ftjQIZmZ2UovD08vr2Upy0cMHx4dHYVq2OZ26H108GAoaKftjHru2eBegRqdXiwWXy4uHj9xEs0wkMjAtT054gk7+jEMu/2rrwICAmBI0Wg1JpoOCw3pl9BPJHI4FjTF3qgI7xb6ZUxKWlT6gtjlK3rOfB05bCD08hX6+wgDfElfL2SyQcjiGeLAQKG/r8SvV1nGnXTAEeAeBQf12v/N1xCQ+t3Xz6DXwwAhEgqnvN5Fsec2774zXaW2rLcROFb488+gHwxpDM3MnPEuqtESJGn5HYORY55/dvSYc+fOUxQ1aswLUbG9YUhANdoKnA44O3Dsd+LYAre+8D91s4o3QljmNxyhWVXHj4RXuV1Zf+XqUUFQgTLhOBn128T3kdVsnjVnbkCvkMjY+KCwyEGPPgZvm7eXlpUFBoeFRcZExMZ7+/VY8NFi3n43N67fULj7wBl69AqdOv09ZO0Y0IFCw6PComIjY3tHxMTDyQNDwkeNGYfcdomK66P08r106RJsnzx1WqrwCI+MNRgsiwZtxV4vtKQPDtOsapuSFAcrw+VC/FuXmSESod/HCe7VKzV5aX29Cnwenp7Z2Rt++s9Z3tUFCEnytSmTNCoNbFuzYzNo8MFMx9c9MMpo+TAyNjbGTeEGg2p5RTnvqKyqgv9rqmsqypEFKDz787Lk1G2ffwF5ADJZaUnC2+Gi62n1pTEzhjW55kmv/nPE8L/pNFpoCR5enhP+OQk5bNGxNdJmvPfuOxKZGMYR2IY727dvn6FDh/Au+6BrsLZevV5nNBkJgoQZTlb2+lDo1PH9Pv1sG/xNGPAQTDGhDnTuF1+Z8NLLL3762RdePgGNW2oLElp+tqe7aO2l4Z3DyIt2Gsjfslkmk9E0DbNDlUrTSlDs2BppM9zd3UNDQlnWEgogSM98dzpytAZcA8jHT2cXLlisrq2bNHGCm5sbxNeQ4F6EULh9567nnntu0KCHwThn3od7v9m7Oj0tJipqS94nQrF45Og7HxM1l9AMN9Fu2ulUMMsI2eY7LJNJczZkq1QquI/u7sodu3btP2BzsdRy79BmJ3D06PFz5y+AEtCAIsMjRo8aiRwOIJfLZ8+bHx0bf/HS5d27v165Ej0Ob2mOFJW1ZvVn+Xn79uxmaPrbAweU3l49A3uCNzg42MfbS6XWnDmDFpmbTipgkCLIH8MfE9zV0rsCGOLg9d2U/DNUbeLvI4ZPGP/Sjl27QULI1ye/9sa1kssyaQvrW5Z+bN1Yty47dWU61LfutYyRMj4+bNjWLXlo/y5WpKd7KJVmgaULLl20EFkdQ6fVZa/JCAkNQfsNQEOE9w9hld/V6Q0URYMFJqC8BaYxkARTDRGxSS+0JBY4xplojmG7odCs5QF+jGhfN8lelxkY4A/JKg5zDLF47LhWPuVhOY6GGQDL2ingpps+RNKYwsKff/zprEgqgXo9/QNenTgROVri0OHDGzbc+ZIXNFNoSTp9C7/SxLfg20keNLIe8L5MpqtXr/IWPajLsv0T+vO7SEKYj1uUo0yW37Jj2O4rcBkmuAyOsVwGf20AwzCQLJggiwev7R+Hy9+SB00bWivkiscLCrLX33lUEJq2CQ62nMMEZ7NYODPrAHyq0iIr0lYplW5wp7V63eTJk+wsPUIfhSY1fXpiQcEJZNGooYlUVlbyu43R6XQmFhrXna+DLVu8iMDwzMxs2D59+oeSPy/PTZrt4enOe9EC24WxibqiyzCR562OA2/A5h1tzWsHzkD5jBwetQYNTanLV36zd59UKoHhZfOmjQkJfXj73axavWbnrq8lUgm8r5qa2u+PHfX2sawzVFZVPv7EP7y9vYwGw99HjEhJXrJly9bsnE8UbncW7e4G+vSgRx5Z83E62m9EcXHJfQ8O9PH1AY2hw5wvPCtXyJGvJd6b8UHRb7/t27tbr9O++ea0G7cqhYQQJ7DRI0d+8P6decjSZckHDh3GCcLT3X3a1MRnn3mat//yy6/LV6ykGAYXYONffrHxmp9FQhCxodf+1YD7C+Mq2ulU3nhr6rcHDyoUCrVa/cZrk1OTlyFHl2OV0Npd2of9Yzty5v9lbt2qjo1PgGkoDNAmiir86UyXfS5xN5YW2pG7bP/Yv6R+wKqMNaSQxDEM8hEY67pRPwDFQheOYzAawyOiZdZPviD1OH3ieHh4OO/qFpwSJ/7awIQSkkkIsaDlsKFDulc/wNUL20yv0AiRSAQSqupVRw7t699/AHJ0E65e2DbSV62uKC2rq62/XnGjT5/4btcPcPXCtnHu3HmaoaELMgwbFhrivK+cOY5Lwnse10B6jyMQ/D/exLg8R/4sQAAAAABJRU5ErkJggg==",
        "authenticatorGetInfo": {
            "versions": [
                "U2F_V2",
                "FIDO_2_0",
                "FIDO_2_1_PRE"
            ],
            "extensions": [
                "credBlob",
                "credProtect",
                "hmac-secret"
            ],
            "aaguid": "e1a9618350164f24b55be3ae23614cc6",
            "options": {
                "uv": true,
                "userVerificationMgmtPreview": true,
                "credMgmt": true,
                "uvBioEnroll": true,
                "rk": true,
                "plat": false,
                "clientPin": false,
                "up": true,
                "bioEnroll": true,
                "credentialMgmtPreview": true
            },
            "maxMsgSize": 2048,
            "pinUvAuthProtocols": [
                1
            ],
            "maxCredentialCountInList": 20,
            "maxCredentialIdLength": 128,
            "transports": [
                "usb"
            ],
            "algorithms": [
                {
                    "type": "public-key",
                    "alg": -7
                },
                {
                    "type": "public-key",
                    "alg": -8
                }
            ],
            "firmwareVersion": 10013
        }
    }
}

    Create FIDO Policy - all FIDO-certifiied authenticators

    Create FIDO Policy - specific authenticators

    Add Custom FIDO Device - u2f

    Add Custom FIDO Device - fido2

    Read All FIDO Policies

    Read All FIDO Device Metadata

    Read Single FIDO Policy

    Read FIDO Device Metadata - single u2f device

    Read FIDO Device Metadata - single fido2 device

    Update FIDO Policy

    Delete Single FIDO Policy

    Remove Custom FIDO Device

    Remembered Devices

    To reduce the friction of frequent authentication requests, your MFA policies can allow the use of a "remember me" option. When you enable this option, you specify the maximum time a device can be remembered. During this period, if a user tries to access applications from the same computer and browser, they will not be asked for further authentication.

    The use of this feature requires the following elements:

    • Embedding the Signals SDK in the UI of your application.
    • Adding a "remember me" option to the UI of your application.
    • Enabling the "remember me" option in the MFA policies that you plan on using.
    • Sending an API request with the relevant information so that the user's browser is recorded as a remembered device.
    • When the user subsequently tries to access an application, sending the API request that compares the current browser information with the information that was recorded previously.

    Creating a remembered device

    To create a remembered device:

    1. Get the ID of the MFA policy that is being used.
    2. Get the details of the MFA policy.
    3. Check the content of the rememberMe object in the MFA policy to see if the "remember me" option can be used with this policy (rememberMe.web.enabled).
    4. If "remember me" is enabled, send a request using the devices endpoint, as shown in the Create Remember Me Device example.
    5. The response to the request will include a cookie in the set-cookie header. When it comes time to check if a device is remembered, you will have to include this cookie in the headers for the request.

    Checking if device is recognized

    To check if a user is using a remembered device:

    1. Get the ID of the MFA policy that is being used.
    2. Get the details of the MFA policy.
    3. Check the content of the rememberMe object in the MFA policy to see if the "remember me" option can be used with this policy (ememberMe.web.enabled).
    4. If "remember me" is enabled, send a request using the deviceAuthentications endpoint and the application/vnd.pingidentity.payload.check+json header, as shown in the Check if Device Remembered example. The headers must also include the cookie that was returned when the remembered device was created. Note that if you included the PingOne session ID by using the optional session.id parameter when creating the remembered device, you must include the deviceSession.id parameter when checking if the device is remembered.

    Create Remembered Device data model

    Property Type Required? Mutable? Description
    cookiesEnabled Boolean N/A Read-only Whether cookies are enabled for the browser.
    createdAt Date N/A Read-only The date and time the remembered device was created.
    environment.id String N/A Read-only The ID of the PingOne environment.
    id String N/A Read-only The ID of the remembered device.
    jsFingerprint String N/A Read-only The fingerprint of the browser.
    lastRememberedAt Date N/A Read-only The date and time that the create remember me request was last sent for this device.
    locale String N/A Read-only The locale set on the device.
    name String N/A Read-only The name of the browser.
    nickname String N/A Read-only The browser nickname.
    operatingSystem.name String N/A Read-only The operating system installed on the device.
    operatingSystem.version String N/A Read-only The version of the operating system installed on the device.
    payload String Required Mutable The payload from the Signals SDK .
    policy.id String Required Mutable The ID of the relevant MFA policy. For creating a remembered device, you must use an MFA policy that has been enabled for the "remember me" feature.
    pushNotificationSupport Boolean N/A Read-only Whether push notifications are enabled for the browser.
    screenResolution.height Integer N/A Read-only The screen resolution height.
    screenResolution.width Integer N/A Read-only The screen resolution width.
    session.id String Optional Mutable For an added layer of security, you can also include the ID for a user's PingOne session. This parameter is optional, however, if you include it when creating the remembered device, you must also include the session ID (deviceSession.id) when you try checking if the device is remembered.
    status String N/A Read-only The status of the device, for example, ACTIVE.
    type String Required Immutable Must be set to BROWSER.
    updatedAt Date N/A Read-only The date and time the remembered device was last updated.
    userAgent String N/A Read-only User agent string for the browser.
    version String N/A Read-only The version of the browser.

    Check Remembered Device data model

    Property Type Required? Mutable? Description
    authenticators Array N/A Read-only Included in response when checking if device is a remembered device. If the device was recognized as a remembered device, the array will contain the values rm, mfa, and swk.
    bypassAllowed Boolean N/A Read-only Indicates whether the authentication policy allows users to bypass MFA if they do not have a compatible authentication method.
    createdAt Date N/A Read-only The date and time the remembered device was created.
    deviceSession.id String Optional Mutable If you included the ID for a PingOne user session when creating the remembered device, you must also include the session ID when checking if the device is a remembered device. When creating the remembered device the parameter to use is session.id. When checking if the device is a remembered device, the parameter to use is deviceSession.id.
    environment.id String N/A Read-only The ID of the PingOne environment.
    id String N/A Read-only The ID of the flow.
    payload.type String Required Immutable Value must be set to BROWSER.
    payload.value String Required Mutable The payload from the Signals SDK.
    policy.id String Required Mutable The ID of the relevant MFA policy.
    selectedDevice.id String N/A Read-only The ID of the remembered device.
    status String N/A Read-only The status of the check - COMPLETED if the device was recognized as a remembered device, FAILED if not.
    updatedAt Date N/A Read-only The date and time the remembered device was last updated.
    user.id String Required Mutable The ID of the user. Required when checking if the device is a remembered device.
    userBypassEnabled Boolean N/A Read-only Indication of whether the specific user is currently permitted to bypass MFA.
    _embedded.blockedDevices Array N/A Read-only Lists any of the users's authentication methods that are currently blocked.
    _embedded.devices Array N/A Read-only Information on all of the authentication methods registered for the user.

    Create Device Authentication Policy (with Remember Me enabled)

    Create Remember Me Device

    Check Remember Me Device

    PingOne Neo

    PingOne Neo is a decentralized identity solution that gives control of identity data back to users. PingOne Neo empowers businesses to give their users full control over how they securely store and share verified credentials without unnecessary friction.

    PingOne Neo also provides organizations with identity verification capabilities and the capability to issue credentials for users to store in their wallet app and verify user data with access to:

    PingOne Credentials A self-service interface included to customize and issue verifiable digital credentials that users can store in their wallet app with no code required.

    PingOne Neo Native SDK Embed personal identity using the SDK into a service to issue digital cards to users and let them store verifiable, shareable data in their wallet app. It is composed of PingOne Credentials, PingOne Verify, and a unified SDK, PingOne Neo SDK.

    PingOne Verify Enabled secure user identity verification based on a government-issued document and live face capture (a selfie) using the PingOne Verify Integration Kit. For more information, see PingOne Verify Integration Kit.

    For more information, see PingOne Neo.

    PingOne Credentials

    Use the Credentials service to create custom verifiable credentials for users. The resulting credentials can then be shared with compatible wallet apps. The Credentials service enables you to:

    Automatic deletion and revocation

    Typical behavior for credential types is to automatically revoke user credentials when a credential type, user, or environment is deleted. However, some credential types, such as birth certificates, university degrees, or marriage certificates, should never be automatically revoked even if the user or environment is deleted. You control this using onDelete.revokeIssuedCredentials on the credential type.

    The selected deletion and revocation behavior cascades over all resources managed by the service: credential types, issuance rules, staged changes, digital wallet applications, digital wallets, and user credentials.

    Environment deleted:

    • Delete all credential types

    • Delete all issuance rules

    • Delete all staged changes

    • Delete all digital wallet applications

    • Delete all digital wallets

    • Delete all user credentials

    • Delete all provisioned credentials

    • Delete all credential type counts

    • Delete environment credential count

    Population deleted:

    • Remove population from existing issuance rules

    Group deleted:

    • Remove group from existing issuance rules

    User deleted:

    • Delete user credential

    • Delete digital wallets

    Application (associated with digital wallet applications) deleted:

    • No impact

    Credential type deleted:

    • Revoke issued credentials based on delete flag

    • Delete issuance rule

    Issuance rule deleted

    • Delete staged changes

    Digital wallet application deleted:

    • Disable digital wallets that are of this type

    Digital wallet deleted:

    • Revoke credentials that were provisioned to the digital wallet based on credential type delete flag

    User credential deleted:

    • Revoke provisioned credentials based on credential type delete flag

    Regardless of the setting of onDelete.revokeIssuedCredentials, the service always deletes any pending credentials. (Pending credentials are staged for issue but not provisioned to a wallet because no paired digital wallet exists.)

    Credential Issuers

    Use the Credential Issuers operations to retrieve or update the credential issuer information. A credential issuer profile, which enables issuance of credentials, is automatically created when the credential service is added to an environment.

    Credential Issuers data model

    Property Type Required? Mutable? Description
    applicationInstance.id String N/A Read-only Identifier (UUID) of the application instance registered with the PingOne platform service. This enables the client to send messages to the service.
    createdAt DateTime N/A Read-only Date and time the issuer profile was created.
    id String N/A Read-only Identifier (UUID) of the credential issuer.
    logo String Optional Mutable A URI containing the logo for the issuer. Restricted to a valid URL with a scheme of https: or a scheme of data: with a base64-encoded image. Included in credentials issued.
    name String Required Immutable The name of the credential issuer. Included in credentials issued.
    siteUrl String Optional Mutable URL, chosen by the issuer, that references the issuer in issued credentials.
    updatedAt DateTime N/A Read-only Date and time the credential issuer profile was last updated; can be null.

    The logo and name can be shown to the user when indicating the credential issuer by the wallet app using using the PingOne Neo Native SDKs with getIssuerMetadata for Android and getCredentialIssuerMetadataFromClaim(_:) for iOS.

    Response codes
    Code Message
    200 Successful operation.
    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.
    500 Unexpected server error.

    Read Credential Issuer Profile

    Update Credential Issuer Profile

    Credential Types

    Use the Credentials Types operations to create, read, and update the credential types used by compatible wallet apps.

    Versioning

    If the updated credential type differs from the existing credential type, the service saves the existing credential type as a Credential Type Version and increments version.number in the updated credential type. Credential Type Versions can be read with Read All Credential Type Versions.

    Credential schema

    When the service creates a credential from a credential type, it maintains the full credential schema, including attributes without corresponding values in the Create a User Credential request, so that the credential structure is consistent and predictable. It assigns an empty string ("") to any attribute without a value in the request body.

    Credential Types data model

    Property Type Required? Mutable? Description
    cardDesignTemplate String Required Immutable An SVG formatted image containing placeholders for the credentials fields that need to be displayed in the image. See warning following this table. Not returned with Read All Credential Types. You must Read One Credential Type with the id of the credential type you want to review.
    cardType String Optional Mutable A descriptor of the credential type. Can be non-identity types such as proof of employment or proof of insurance.
    createdAt DateTime N/A Read-only Date and time the credential type was created.
    deletedAt DateTime N/A Read-only Date and time the credential type was deleted. Returned only with Read One Credential Type.
    description String Optional Mutable A description of the credential type.
    environment.id String N/A Read-only PingOne environment identifier (UUID) in which the credential type exists.
    expiration Object Optional Mutable Object that identifies how to evaluate the expiration date. Requires one and only one of after, timestamp, or expression. Permitted only when management.mode is AUTOMATED.
    expiration.after Object Required/Optional Mutable Contains the numeric duration and its time unit for calculating an expiration date.
    expiration.after.duration Integer Required Mutable Length of time before transaction timeout expires; range is from a 1 hour minimum (or equivalent) to an (effectively) unbounded maximum.
    expiration.after.timeUnit String Required Mutable Time unit of transaction timeout; can be SECONDS, MINUTES, HOURS, or DAYS.
    expiration.expression String Required/Optional Mutable PingOne Expression Language (PEL) expression that evaluates to an ISO 8601 date. For more information on PEL, see PingOne expression language.
    expiration.fieldName String Required/Optional Mutable On issuance, name of the field in the credential to hold the expiration that, when evaluated, returns an expiration date. Must be unique from all fields defined in the metadata object of Create Credential Type. Required when expiration.type is SOFT. Optional when expiration.type is HARD and ignored if used.
    expiration.timestamp DateTime Required/Optional Mutable The date and time to expire in ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ format (milliseconds optional).
    expiration.type String Required Mutable Indicates how expiration of the credential is presented. Can be SOFT or HARD. A SOFT expiration appears as a user-defined field (named in fieldName) in the credential but returns no expiration date in Read One User Credential. A HARD expiration appears as a standards-based expiration field in the credential and returns an expiration date in Read One User Credential.
    id String N/A Read-only Identifier (UUID) associated with the credential type.
    issuer.id String N/A Read-only The identifier (UUID) of the issuer.
    issuerName String Optional Mutable Issuer name associated with the card, can differ from title.
    management.mode String Optional Mutable Management mode of the credential type. Can be AUTOMATED (the default) or MANAGED. See the note following this table.
    metadata Object Required Mutable Contains the names, data types, and other metadata related to the credential; see metadata object data model.
    multiple Object Optional Mutable Object containing directives that enable you to Issue multiple credentials to a user based on a directory attribute.
    multiple.expression String Required Mutable A PingOne Expression Language (PEL) expression that evaluates to a number or array. If an array, calculates the array length for the count. Populates the limit to a variable, __ITERATOR__, available to PEL expressions in metadata.fields.attribute.
    onDelete.revokeIssuedCredentials Boolean Optional Mutable Whether user credentials are automatically revoked when a credential type, user, or environment is deleted. Defaults to true. For credential types (such as birth certificates, university degrees, or marriage certificates) that should never be automatically revoked even if the user or environment is deleted, set this to false.
    title String Required Immutable Title of the credential. Verification sites are expected to be able to request the issued credential from the compatible wallet app using the title.
    updatedAt DateTime N/A Read-only Date and time the credential type was last updated; can be null.
    version.number Integer N/A Read-only Version of this credential type. The service assigns versions.
    version.uri String N/A Read-only A URI to of this version of the credential type. The service assigns URIs.

    If management.mode is AUTOMATED, the credential type is only issued by its associated credential issuance rule. If management.mode is MANAGED, the credential type is only issued by Create a User Credential or Update a User Credential API requests. If you change management.mode from AUTOMATED to MANAGED and an associated issuance rule exists, the rule is disabled, but not deleted.

    If management.mode is AUTOMATED, you can value one and only one of the three properties in the expiration object and the associated credential issuance rule automatically assigns an expiration date when it issues the credential. If management.mode is MANAGED and an expiration object is present, it causes an error.

    If you want to change management.mode from AUTOMATED to MANAGED, but one of the three properties in the expiration object is valued, you must remove the expiration object. Use Update the Credential Type with no expiration object, which removes it from the credential type, and with management.mode set to MANAGED.

    metadata object data model

    The metadata object is not returned with Read All Credential Types. You must Read One Credential Type with the id of the credential type you want to review.

    Property Type Required? Mutable? Description
    backgroundImage String Optional Mutable URL to an image of the background to show in the credential. Must be no more than 50 KB in size.
    bgOpacityPercent String Optional Mutable Percent opacity of the background image in the credential. High percentage opacity may make reading text difficult.
    cardColor String Optional Mutable Color to show on the credential.
    columns Integer Optional Mutable Number of columns of visible fields to use when displaying the credential. Must be between 1 and 3. Defaults to 1.
    description String Optional Mutable Description of the credential.
    fields Object[] Optional Mutable Array of objects representing the fields.
    fields.attribute String Required/Optional Mutable Name of the PingOne Directory attribute. Required if field.type is Directory Attribute, otherwise optional and ignored if used. See fields.attribute definition.
    fields.default String Optional Mutable Assigns a default value if a PingOne Expression Language (PEL) in the fields.attribute evaluates to no value.
    fields.id String Required Mutable Identifier of the field. Ping Identity recommends that id is text formatted as "<fields.type> -> <fields.title>" to show the type of data expected as well as for what it is used. Examples include: "Alphanumeric Text -> Department" or "Directory Attribute -> Username".
    fields.fileSupport String Optional Mutable Specifies how an image is stored in the credential; see fields.fileSupport types.
    fields.isVisible Boolean Required Mutable Whether the field should be visible to viewers of the credential.
    fields.required Boolean Optional Mutable Whether the field is required for the credential. Defaults to false.
    fields.title String Required Mutable Descriptive text when showing the field.
    fields.type String Required Mutable Type of data in the field; see fields.type types.
    fields.value String Required/Optional Mutable The text to appear on the credential for a type of Alphanumeric Text. Required if type is Alphanumeric Text and management.mode is AUTOMATED, optional if type is Alphanumeric Text and management.mode is MANAGED (effectively a default that can be overridden by a data value in Create a User Credential or Update a User Credential), and otherwise ignored if present.
    logoImage String Optional Mutable URL to an image of the logo to show in the credential. Must be no more than 25 KB in size.
    name String Optional Mutable Name of the credential.
    textColor String Optional Mutable Color of the text to show on the credential.
    version Integer Optional Mutable Version of this credential metadata. If not provided, the service assigns a version.
    fields.attribute definition

    Although fields.attribute is always a string type, the service supports two interpretations of its string.

    If the string begins with ${ and ends with }, the string is interpreted as a PingOne Expression Language (PEL) expression. As a PEL expression, the string must have user. before any attribute names. A PEL expression is essential to Issue multiple credentials to a user based on a directory attribute. The PEL expression extracts specific elements from the multiple potential credentials found in the attribute.

    If the string does not have ${ and }, the string is interpreted as the traditional pointer to an attribute name in the directory. That is, you supply an attribute name as the string and the service supplies the value of that attribute to the credential. When used as a pointer, the string does not need user. to reference an attribute.

    fields.fileSupport types

    A credential field that uses a type of Directory Attribute can contain a URL that references a JPEG, PNG, or GIF image file uploaded with Create Image. The credential type is limited to 5 fields that have fileSupport set to BASE64_STRING or INCLUDE_FILE. For credentials, an image file has a maximum size of 2 MB. A credential cannot exceed 2.5 MB including all images.

    Type Description
    BASE64_STRING Image is base64-encoded to a string in the credential.
    INCLUDE_FILE Image binary is included in the credential.
    REFERENCE_FILE Only a URL referencing the image is in the credential. The image binary remains stored external to the credential.
    fields.type types
    Type Description
    Alphanumeric Text A static text string of letters, numbers, or punctuation set on fields.value.
    Issued Timestamp Date and time the credential was issued.
    Directory Attribute Any PingOne Directory standard or custom attribute. When used in a credential for a user, the service reads that attribute from the user and puts the value in the credential. The name of the attribute is in fields.attribute.

    Automatic deletion and revocation

    Typical behavior for credential types is to automatically revoke user credentials when a credential type, user, or environment is deleted. However, some credential types, such as birth certificates, university degrees, or marriage certificates, should never be automatically revoked even if the user or environment is deleted. You control this using onDelete.revokeIssuedCredentials on the credential type.

    The selected deletion and revocation behavior cascades over all resources managed by the service: credential types, issuance rules, staged changes, digital wallet applications, digital wallets, and user credentials.

    If onDelete.revokeIssuedCredentials is true:

    • User credentials are revoked and deleted when the credential type is deleted.

    • Provisioned credentials are revoked when a user credential is deleted, its credential type is deleted, or its digital wallet is disabled or deleted.

    If onDelete.revokeIssuedCredentials is false:

    • User credentials are only revoked if the issuance rule causes it to be revoked or if Update a User Credential sets the expiration date.

    • Provisioned credentials are revoked if the user credential is revoked (see previous item).

    Issue multiple credentials to a user based on a directory attribute

    Some customers must issue multiple credentials to a user based on a directory attribute. For example, a bank might issue credit cards in their own name while also issuing credit cards branded for their customers. A user may have more than one of these credit cards in their wallet. The directory service requires an attribute that contains all the credit cards for that user and the service must support credential issuance to any or all of that user's credit cards.

    The customer can define a single directory attribute for each user to hold a data object that contains the different accounts owned by the user. Our hypothetical bank wants to support the end user being able to present a verifiable credential that contains only the information from one of these accounts. Although issuance of multiple credentials is initiated by a single directory attribute, definition of the credential type can reference any directory attributes for its fields.

    The definition of the data object is up to the customer. They then use PingOne Expression Language (PEL) expressions to retrieve any information as required. The Credential Types multiple.expression contains a PEL expression that counts qualifying entries in the data object. The Credential Types metadata.fields.attribute contains a PEL expression to retrieve individual data elements that populates a field in the credit type definition.

    When you Apply Credential Issuance Rule Staged Changes for a user for a credential type that has multiple configured, the service creates multiple, separate user credentials for the credential type.

    An example may better illustrate applying these concepts.

    Example data object

    Our hypothetical bank customer, BigBank, uses this JSON object, stored as a JSON binary large object (blob), as the source for credit card information.

    {
  "credit_cards": {
    "branded": [
      {
        "oem_merchant": "ChainRetailer",
        "customer_id": "0010380",
        "user_id": "1506980157738"
      },
      {
        "oem_merchant": "GlobalOil",
        "customer_id": "0475932",
        "user_id": "1506980157739"
      }
    ],
    "owned": [
      {
        "customer_id": "0010380",
        "int_id" : "03918203198"
      },
      {
        "customer_id": "0475932",
        "int_id" : "03918203100"
      }
    ]
  }
}

    An administrator at BigBank creates two different credential types, one each for branded and owned. Each credential type is configured to issue a credential for each JSON object in that array.

    Example API

    This demonstrates the API using the branded array. An administrator at BigBank created this credential type for branded.

    A body for Create a credential type (automated) that creates multiple credentials from the data object for the credit_cards.branded is:

    {
    "title": "Branded Cards",
    "description": "Example for branded cards attribute for BigBank",
    "metadata": {
        "fields": [
            {
                "id": "title",
                "title": "oem_merchant",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].oem_merchant}",
                "isVisible": true,
                "type": "Directory Attribute",
                "default": "Use this if missing"
            },
            {
                "id": "Directory Attribute -> user_id",
                "title": "user_id",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].user_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            },
            {
                "id": "Directory Attribute -> customer_id",
                "title": "customer_id",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].customer_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            }
        ]
    },
    "cardDesignTemplate": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 740 480\">...</svg>",
    "multiple": {
        "expression": "${user.credit_cards['branded']}"
    }
}

    The PEL expression in multiple.expression returns the count of objects in the credit_cards.branded object array of the data object. This populates the iteration limit of the system __ITERATOR__ variable seen in the PEL expressions of the three metadata.fields.attribute values.

    A body for Create a credential type (automated) that creates multiple credentials from the data object for the credit_cards.owned is:

    {
    "title": "Owned",
    "description": "Example for owned attribute for BigBank",
    "metadata": {
        "fields": [
            {
                "id": "Directory Attribute -> int_id",
                "title": "int_id",
                "attribute": "${user.credit_cards['owned'][__ITERATOR__].int_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            },
            {
                "id": "Directory Attribute -> customer_id",
                "title": "customer_id",
                "attribute": "${user.credit_cards['owned'][__ITERATOR__].customer_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            }
        ],
        "textColor": "#000000",
        "version": 4
    },
    "cardDesignTemplate": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 740 480\">...</svg>",
    "multiple": {
        "expression": "${user.credit_cards['owned']}"
    }
}

    The PEL expression in multiple.expression returns the count of objects in the credit_cards.owned object array of the data object. This populates the iteration limit of the system __ITERATOR__ variable seen in the PEL expressions of the two metadata.fields.attribute values.

    Important considerations

    1. Do not use a multi-valued attribute type. Use a single JSON attribute that contains the necessary arrays.

      When configuring a custom JSON attribute for issuing multiple credentials for a user, the administrator can set it to a multi-valued type, which allows the attribute to be an array of JSON blobs. The PingOne Directory does not guarantee ordering for multi-valued attributes. Multi-valued attributes values are treated as a set rather than a list. This conflicts with how the service determines if a credential has changed, where order is essential. For example, a user has three credentials issued using a multi-valued type of [A, B, C]. If you add another JSON blob to the user attribute, one might expect the change to look like [A, B, C, D] (where each letter is a different credential) and issue one more credential to the user. However, with a multi-valued custom JSON attribute, the change may look like [A, C, D, B]. When the service compares the order, it interprets that two credentials have been updated and one more credential has been added.

      Due to this involuntary re-ordering behavior, multi-valued custom JSON attributes are strongly discouraged.

    2. Revocation can be affected by re-ordering.

      If the user has an array like [A, B, C] so that the service issues three credentials and an administrator then revokes the credential B, credential B remains revoked. If the user is updated to change some values in A, B, and C, A and C update while B remains revoked. However, if the user is updated with a new object or value added to the array such that it becomes [A, D, B, C], credential C updates to the values of B and a new credential issues for C. No credential will be issued or updated to have the values of D because it is in the second place and the credential for second place was revoked.

      To mitigate this behavior, always add new entries to the end of the arrays in the JSON blob.

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Unexpected server error.

    Create Credential Type (automated)

    Create Credential Type (managed)

    Read All Credential Types

    Read All Credential Type Versions

    Read One Credential Type

    Read One Credential Type Version

    Update a Credential Type

    Delete a Credential Type

    Credential Issuance Rules

    Use the Credentials Issuance Rules operations to create, read, and update rules for issuing, updating, and revoking credentials by credential type. Rules are defined for:

    • A specific Credential Type in the endpoint

    • A specific Digital Wallet App in the request body

    • A specific set of users defined by one, and only one, of these filters in the request body:

    A credential rule contains an automation object with available actions as keys: issue, revoke, and update. If an action is set to PERIODIC, the service performs the action at the end of the period. If an action is set to ON_DEMAND, you must use Apply Credential Issuance Rule Staged Changes to perform staged changes for those ON_DEMAND actions.

    The general procedure for rules is:

    1. Create - create a new rule to stage actions for for the credential by user

    2. Update - update an existing rule to stage actions for the credential by user

    3. Staged Changes - show actions staged for execution

    4. Apply - act upon credentials staged for actions.

    You can also monitor credential rules:

    • All Rules - view all rules defined for a credential type

    • One Rule - view a specific rule for a credential

    • Usage Counts - show counts by action applied to the credential by user

    • Usage Details - show details by action applied to the credential by user

    You can, finally, remove a rule for a credential type:

    • Delete - remove a rule from a credential type

    For actions set to PERIODIC, an improper credential could cause endless repetitious errors. The service monitors staged changes for errors. When an error occurs during processing, the service adds details of the error to the staged change so that errors can be tracked, counted, and returned to the user. If more than 3 errors occur for the same scheduled staged change, the service unschedules (changes stagedChanges.scheduled from true to false) that staged change so that the service no longer attempts to process it. The user can manually trigger the staged change with Apply Credential Issuance Rule Staged Changes.

    Credentials unscheduled due to errors are reported. Some errors are known but there can also be unexpected errors. The errors.errorDetail object provides an error code and message. If the error was related to processing a specific credential field, the field name will be in errors.errorDetail.target. This includes the staged changes that exist when the request is made with 1 or more errors. It does not include a staged change that was failed in the past, but has since completed successfully or was deleted (because the user no longer matches the issuance rule). Requests that report errors include:

    Credential Issuance Rules data model

    Property Type Required? Mutable? Description
    automation Object Required Mutable Contains a list of actions, as key names, and the update method for each action.
    automation.issue String Required Mutable The method the service uses to issue credentials with the credential issuance rule. Can be PERIODIC or ON_DEMAND.
    automation.revoke String Required Mutable The method the service uses to revoke credentials with the credential issuance rule. Can be PERIODIC or ON_DEMAND.
    automation.update String Required Mutable The method the service uses to update credentials with the credential issuance rule. Can be PERIODIC or ON_DEMAND.
    createdAt DateTime N/A Read-only Date and time the credential issuance rule was created.
    credentialType.id String N/A Read-only Identifier (UUID) of the credential type with which this credential issuance rule is associated.
    digitalWalletApplication.id String Optional Mutable Identifier (UUID) of the customer's Digital Wallet App that will interact with the user's Digital Wallet. Optional, and if present, digital wallet pairing automatically starts when a user matches the credential issuance rule.
    environment.id String N/A Read-only PingOne environment identifier (UUID) in which the credential issuance rule exists.
    filter Object Optional Mutable Contains one and only one filter (.groupIds, .populationIds, or .scim) that selects the users to which the credential issuance rule applies.
    filter.groupIds String[] Required/Optional Mutable Array of one or more identifiers (UUIDs) of groups, any of which a user must belong for the credential issuance rule to apply. One and only one filter is required in filter, others are optional and cause an error if used.
    filter.populationIds String[] Required/Optional Mutable Array of one or more identifiers (UUIDs) of populations, any of which a user must belong for the credential issuance rule to apply. One and only one filter is required in filter, others are optional and cause an error if used.
    filter.scim String Required/Optional Mutable A SCIM query that selects users to which the credential issuance rule applies. One and only one filter is required in filter, others are optional and cause an error if used. For more information about SCIM syntax and operators, see Filtering collections.
    id String N/A Read-only Identifier (UUID) of the credential issuance rule.
    notification Object Optional Immutable Contains notification information. When this property is supplied, the information within is used to create a custom notification.
    notification.methods String[] Optional Immutable Array of methods for notifying the user; can be EMAIL, SMS, or both.
    notification.template Object Optional Immutable Contains template parameters.
    notification.template.locale String Optional Immutable The ISO 2-character language code used for the notification; for example, en.
    notification.template.variables Object[] Required/Optional Immutable An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, see Dynamic variables.
    notification.template.variant String Optional Immutable The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
    status String Required Mutable Status of the credential issuance rule. Can be ACTIVE or DISABLED.
    updatedAt DateTime N/A Read-only Date and time the credential issuance rule was last updated; can be null.

    Actions within automation (.issue, .update, and .revoke) can be PERIODIC, the service applies the rule frequently every hour, or ON_DEMAND, the service applies the rule only with an Apply Credential Issuance Rule Staged Changes request. For ON_DEMAND, use Read Credential Issuance Rule Staged Changes to determine staged changes.

    The one notification.template object applies a variant and locale to all three credential notification templates: credential_issued, credential_updated, and credential_revoked. When adding a variant or locale to any of the three notification templates, consider adding the same variant or locale to the other notification templates. If a requested variant is not defined, the notification uses the default notification template. If a requested locale is not defined, the notification uses the user's preferred language or, if the user has no preferred language, the default language of the environment.

    Credential Issuance Rules staged changes data model

    Property Type Required? Mutable? Description
    stagedChanges.action String N/A Read-only Action determined by the service that should be taken for the credential based on the request that staged it. Can be ISSUE, UPDATE, or REVOKE.
    stagedChanges.createdAt DateTime N/A Read-only Date and time the change was staged by the service.
    stagedChanges.credentialType.id String N/A Read-only Identifier (UUID) of the credential type with which this credential issuance rule is associated.
    stagedChanges.environment.id String N/A Read-only PingOne environment identifier (UUID) in which the credential issuance rule exists.
    stagedChanges.issuanceRule.id String N/A Read-only Identifier (UUID) of the credential issuance rule.
    stagedChanges.scheduled String N/A Read-only Whether or not the staged change is scheduled: true if the action on the credential issuance rule is set to PERIODIC and false if the action is set to ON_DEMAND.
    stagedChanges.user.id String N/A Read-only Identifier (UUID) of the user identified by the filter on the credential issuance rule.
    stagedChanges.errors Object[] N/A Read-only Array of objects representing credentials that had errors when attempting an action on it. See Credential Issuance Rules errors object.

    Credential Issuance Rules apply staged changes data model

    This data model applies only to Read Credential Issuance Rule Staged Changes and Apply Credential Issuance Rule Staged Changes.

    Property Type Required? Mutable? Description
    issue String[] Optional Mutable Array of one or more identifiers (UUIDs) of users whose credentials are in an issue action state and should be issued.
    revoke String[] Optional Mutable Array of one or more identifiers (UUIDs) of users whose credentials are in a revoke action state and should be revoked. Used only in the body of Apply Credential Issuance Rule Staged Changes.
    update String[] Optional Mutable Array of one or more identifiers (UUIDs) of users whose credentials are in an update action state and should be updated. Used only in the body of Apply Credential Issuance Rule Staged Changes.
    errors Object[] N/A Read-only Array of objects representing credentials that had errors when attempting an action on it. See Credential Issuance Rules errors object.

    Credential Issuance Rules usage counts data model

    Property Type Required? Mutable? Description
    issued Integer N/A Read-only Count of credentials issued by the rule since the time the credential issuance rule was created.
    accepted Integer N/A Read-only Count of credentials accepted by users of credentials issued by the credential issuance rule since the time the credential issuance rule was created.
    updated Integer N/A Read-only Count of credentials updated by the rule since the time the credential issuance rule was created.
    revoked Integer N/A Read-only Count of credentials revoked by the rule since the time the credential issuance rule was created.
    errors Integer N/A Read-only Count of credentials that caused errors since the time the credential issuance rule was created.

    Credential Issuance Rules usage details data model

    Property Type Required? Mutable? Description
    issued Object[] N/A Read-only Credentials issued by the rule since the time the credential issuance rule was created.
    issued.user.id String N/A Read-only Identifier (UUID) of the user identified by the filter on the credential issuance rule.
    issued.credential.id String N/A Read-only Identifier (UUID) of the credential subject to the issue action identified by the credential issuance rule.
    issued.createdAt DateTime N/A Read-only Date and time the credential was issued by the service.
    updated Object[] N/A Read-only Credentials updated by the rule since the time the credential issuance rule was created.
    updated.user.id String N/A Read-only Identifier (UUID) of the user identified by the filter on the credential issuance rule.
    updated.credential.id String N/A Read-only Identifier (UUID) of the credential subject to the update action identified by the credential issuance rule.
    updated.createdAt DateTime N/A Read-only Date and time the credential was updated by the service.
    revoked Object[] N/A Read-only Credentials revoked by the rule since the time the credential issuance rule was created.
    revoked.user.id String N/A Read-only Identifier (UUID) of the user identified by the filter on the credential issuance rule.
    revoked.credential.id String N/A Read-only Identifier (UUID) of the credential subject to the revoke action identified by the credential issuance rule.
    revoked.createdAt DateTime N/A Read-only Date and time the credential was revoked by the service.
    errors Object[] N/A Read-only Array of objects representing credentials that had errors when attempting an action on it. See Credential Issuance Rules errors object.

    Credential Issuance Rules errors object

    Property Type Required? Mutable? Description
    errors Object[] N/A Read-only Array of objects representing errors recorded when attempting an action on a credential.
    errors.recordedAt DateTime N/A Read-only Date and time the error was recorded by the service.
    errors.errorDetail.code String N/A Read-only A code that indicates the error encountered by the service. See Credential Issuance Rules staged changes error codes.
    errors.errorDetail.target String N/A Read-only The part of the credential that caused the error encountered by the service.
    errors.errorDetail.message String N/A Read-only A message that describes the error encountered by the service.
    credentialType.id String N/A Read-only Identifier (UUID) of the credential type with which this credential issuance rule is associated.
    environment.id String N/A Read-only PingOne environment identifier (UUID) in which the credential issuance rule exists.
    issuanceRule.id String N/A Read-only Identifier (UUID) of the credential issuance rule.
    user.id String N/A Read-only Identifier (UUID) of the user identified by the filter on the credential issuance rule.
    id String N/A Read-only Identifier (UUID) of the error.
    action String N/A Read-only Action determined by the service that should be taken for the credential based on the request that staged it. Can be ISSUE, UPDATE, or REVOKE.
    scheduled String N/A Read-only Whether or not the staged change is scheduled: true if the action on the credential issuance rule is set to PERIODIC and false if the action is set to ON_DEMAND.
    createdAt DateTime N/A Read-only Date and time the error was created by the service.
    updatedAt DateTime N/A Read-only Date and time the error was updated by the service.
    Credential Issuance Rules staged changes error codes
    Error Code Description
    TEMPLATE_ERROR An error in the template placeholders of the cardDesignTemplate SVG.
    SVG_ERROR An error in the syntax of the cardDesignTemplate SVG.
    CREDENTIAL_TYPE_INVALID Credential Type was invalid when the staged change was performed.
    FILE_RESOLUTION_ERROR User attribute for a field with fileSupport did not reference a supported file, such as an unsupported URL, file too large, or error reading file.
    CREDENTIAL_TOO_LARGE Size of data collected for the credential exceeds the maximum that can be stored in a credential.
    UNEXPECTED_ERROR An unexpected error occurred.

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Unexpected server error.

    Create Credential Issuance Rule

    Read All Credential Issuance Rules

    Read One Credential Issuance Rule

    Read All Credential Issuance Rule Staged Changes

    Read One Credential Issuance Rule Staged Change

    Read Credential Issuance Rule Usage Counts

    Read Credential Issuance Rule Usage Details

    Update Credential Issuance Rule

    Apply Credential Issuance Rule Staged Changes

    Delete Credential Issuance Rule

    Credential Digital Wallets

    Use the Digital Wallets service to provide the resources needed for customers' applications to interact with users' credential wallets.

    Digital Wallet Apps

    The credential digital wallet apps service controls the relationship between the customer's digital wallet app, which communicates with users' digital wallets, and a customer's PingOne application.

    Credential digital wallet app data model

    Property Type Required? Mutable? Description
    application.id String Required Immutable The identifier (UUID) of the PingOne application associated with the digital wallet app.
    appOpenUrl String Required Mutable URL sent in notifications to the user to communicate with the service.
    createdAt DateTime N/A Read-only Date and time the credential digital wallet app was created.
    environment.id String N/A Read-only PingOne environment identifier (UUID) in which the credential digital wallet app exists.
    id String N/A Read-only Identifier (UUID) associated with the credential digital wallet app.
    name String Required Mutable Name associated with the digital wallet app.
    updatedAt DateTime N/A Read-only Date and time the credential digital wallet app was last updated; can be null.
    usesPingOneWalletSDK Boolean Optional Immutable Whether the user's wallet app uses the PingOne Wallet SDK; default is true.

    Create Digital Wallet App

    Read All Digital Wallet Apps

    Read One Digital Wallet App

    Update Digital Wallet App

    Delete Digital Wallet App

    Digital Wallets

    The credential Digital Wallet service controls the relationship between a user's phone wallet app, which uses the Wallet SDK, and the customer's PingOne application. It also offers notifications when the PingOne application communicates with the user's Wallet SDK. Settings on the Digital Wallet configure sending push notifications from PingOne Credentials to the Wallet SDK of the user.

    In the normal digital wallet pairing use case, you use Create Digital Wallet to create the Digital Wallet without the applicationInstance.id and a pairing session is created. The Digital Wallet service uses the digital_wallet_pairing notification template to send the pairing session URL (see appOpen.href in the response) to the user via email or text or you show a QR code (see qrUrl.href in the response) of the pairing session URL to the user. When the user opens the URL, it opens your app or takes them to a page with instructions on how to install the app. When the app opens the URL, it shares its applicationInstance.id with the service using the Wallet SDK.

    Alternatively, you send the applicationInstance.id when you create the Digital Wallet. For example, if you have the user install your app, the user authenticates with your servers. When your app is installed, it creates an application instance. Since the app knows who the user is, the app sends its application instance identifier to your server and then your application sends the applicationInstance.id to the service when creating or updating the Digital Wallet. This creates a Digital Wallet with a known application instance identifier. Activation of the Digital Wallet requires sending some device data, such as SDK version and application bundle ID or package name, to PingOne Credentials:

    1. The service creates a pairing session and sends a pairing request message to the device.
    2. The Wallet SDK receives this request and the app approves the request.
    3. The Wallet SDK sends the device data to PingOne Credentials, which activates the Digital Wallet.

    Credential digital wallet data model

    Property Type Required? Mutable? Description
    applicationInstance.id String Required/Optional Immutable Identifier (UUID) of the application running the Wallet SDK on the user's device and registered with the service. Registration is required before the wallet can be used. Registration is performed by a compatible wallet app using the Wallet SDK, or by the customer application using Create Digital Wallet or one Update Digital Wallet.
    createdAt DateTime N/A Read-only Date and time the credential Digital Wallet was created.
    deviceData Object N/A Read-only Contains metadata collected about the user's Wallet SDK.
    digitalWalletApplication.id String Required Immutable Identifier (UUID) of the customer's PingOne application that interacts with the user's Wallet SDK.
    environment.id String N/A Read-only PingOne environment identifier (UUID) in which the credential digital wallet app exists.
    id String N/A Read-only Identifier (UUID) associated with the credential digital wallet.
    notification Object Optional Immutable Contains notification information. When this property is supplied, the information within is used to create a custom notification.
    notification.methods String[] Optional Immutable Array of methods for notifying the user; can be EMAIL, SMS, or both.
    notification.results Object[] N/A Read-only Array of objects that contain the results of attempts to notify the user.
    notification.results.error Object N/A Read-only Contains information regarding why a notification failed to send.
    notification.results.error.code String N/A Read-only A short alphanumeric code identifying the error.
    notification.results.error.details Object[] N/A Read-only Array of objects that contain details of the error as provided by the source of the error. Exact format varies by source.
    notification.results.error.id String N/A Read-only Identifier (UUID) of the error message.
    notification.results.error.message String N/A Read-only A textual message explaining the error.
    notification.results.method String N/A Read-only Method used in the attempt to notify the user; can be EMAIL or SMS.
    notification.results.notification.id String N/A Read-only Identifier (UUID) of the notification that was sent.
    notification.results.sent Boolean N/A Read-only Whether the notification was successfully sent.
    notification.template Object Optional Immutable Contains template parameters.
    notification.template.locale String Optional Immutable The ISO 2-character language code used for the notification; for example, en.
    notification.template.variables Object[] Required/Optional Immutable An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, see Dynamic variables.
    notification.template.variant String Optional Immutable The unique user-defined name for the content variant that contains the custom message text used for the notification. For more information on variants, see Creating custom contents.
    pairingAttempts Object[] N/A Read-only Array of result objects of all pairing attempts between the Digital Wallet and the Wallet SDK. Not returned when no pairing was attempted or when creating a Digital Wallet.
    pairingAttempts.attemptedAt DateTime N/A Read-only Date and time the credential pairing was attempted.
    pairingAttempts.details Object N/A Read-only Object with details regarding a pairing failure. Not returned when a pairing was successful. Content of the object varies depending on the error as explained in the Description column of Pairing attempt errors.
    pairingAttempts.error String N/A Read-only As listed in the Error column of Pairing attempt error.
    pairingAttempts.message String N/A Read-only Explanation of the error.
    pairingAttempts.success Boolean N/A Read-only Whether the pairing attempt was successful.
    pairingSession Object N/A Read-only Contains information regarding the pairing session.
    status String Optional Mutable Status of the wallet; can be PAIRING_REQUIRED, ACTIVE, EXPIRED, or DISABLED.
    updatedAt DateTime N/A Read-only Date and time the credential digital wallet was last updated; can be null.
    user.id String N/A Read-only Identifier (UUID) of the user associated with the credential digital wallet.

    Pairing attempt errors

    Error Description
    APP_PACKAGE_MISMATCH The package name or bundle ID sent by the Wallet SDK does not match the mobile settings of the PingOne Application (identified by digitalWalletApplication.id), details includes what was sent by the Wallet SDK in appPackage.
    WALLET_ALREADY_PAIRED The digital wallet is already successfully paired or the instance of the Wallet SDK on the device has already been paired with a different digital wallet of the same user. If a user attempts to pair the same digital wallet twice, details includes the new application instance ID in newApplicationInstanceId. If a user attempts to pair the same Wallet SDK instance with a second digital wallet, details includes the existing digital wallet ID in existingDigitalWalletId.
    WALLET_DISABLED Wallet is disabled.
    UNEXPECTED_ERROR An unexpected error occurred in the service, no details object returned.

    The digital wallet service uses the digital_wallet_pairing notification template to send the pairing session URL to the user via email or SMS text. The notification.template object can define a variant and locale for the notification, if needed.

    Provisioned Credentials data model (wallet)

    This object is shared with user credentials. It is returned only with Read One Digital Wallet Credentials and Read One User Credential Wallets. The former returns all user credentials associated with the specified digital wallet, the latter returns all digital wallets associated with the specified user credential.

    Property Type Required? Mutable? Description
    claimReference Object N/A Read-only The serialized JSON object used to create the ClaimReference object returned. This is needed to revoke an issued credential.
    createdAt DateTime N/A Read-only Date and time the credential was provisioned.
    credential.id String N/A Read-only Identifier (UUID) of the user credential associated with the provisioned credential.
    digitalWallet.id String N/A Read-only Identifier (UUID) of the digital wallet associated with the provisioned credential.
    environment.id String N/A Read-only Identifier (UUID) of the environment associated with the provisioned credential.
    expiresAt Date N/A Read-only The date that the provisioned credential expires. If this value is null, the provisioned credential never expires.
    id String N/A Read-only Identifier (UUID) of the provisioned credential.
    status String N/A Read-only Status of the provisioned credential.
    user.id String N/A Read-only Identifier (UUID) of the user associated with the provisioned credential.
    walletActions Object[] N/A Read-only Array of actions taken regarding the provisioned credential.
    walletActions.action String N/A Read-only Action taken regarding the provisioned credential; can be CREDENTIAL_ACCEPTED, CREDENTIAL_REJECTED, CREDENTIAL_REVOKED, or CREDENTIAL_DELETED.
    walletActions.occurredAt DateTime N/A Read-only Date and time that the action occurred.

    Create Digital Wallet

    Read All Digital Wallets

    Read One Digital Wallet

    Read One Digital Wallet Credentials

    Update Digital Wallet

    Delete Digital Wallet

    User Credentials

    Use the User Credentials service to create a user credential and get the credential status. To issue the credential to the user you must first create a credential type (automated) or create a credential type (managed). After you create a credential type, you can issue credentials to users two ways depending on the management.mode of the credential type:

    Regardless of management.mode, you can revoke a user credential, read all user credentials, read one user credential, or read one user credential wallets.

    User Credentials data model

    Property Type Required? Mutable? Description
    createdAt DateTime N/A Read-only Date and time the user credential was created.
    credentialType.id String Required Immutable Identifier of the credential type.
    data Object Optional Mutable Fields submitted for the credential.
    data.<field> String Required/Optional Mutable Fields for user data; see data object data model.
    environment.id String N/A Read-only Identifier (UUID) of the environment associated with the user.
    expiresAt DateTime Optional Mutable The date that the user credential expires. If this value is null, the credential never expires.
    id String N/A Read-only Identifier (UUID) of the user credential.
    notification Object Optional Immutable Contains notification information. When this property is supplied, the information within is used to create a custom notification.
    notification.methods String[] Optional Immutable Array of methods for notifying the user; can be EMAIL, SMS, or both.
    notification.results Object N/A Read-only Contains the results of attempts to notify the user.
    notification.results.error Object N/A Read-only Contains information regarding why a notification failed to send.
    notification.results.method String N/A Read-only Method used in the attempt to notify the user; can be EMAIL or SMS.
    notification.results.notification.id String N/A Read-only Identifier (UUID) of the notification that was sent.
    notification.results.sent Boolean N/A Read-only Whether the notification was successfully sent.
    notification.template Object Optional Immutable Contains template parameters.
    notification.template.locale String Optional Immutable The ISO 2-character language code used for the notification; for example, en.
    notification.template.variables Object[] Required/Optional Immutable An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, see Dynamic variables.
    notification.template.variant String Required Immutable The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
    status String N/A Read-only Status of the user credential.
    title String N/A Read-only Returned as defined in the credential type.
    updatedAt DateTime N/A Read-only Date and time the credential type was last updated; can be null.
    user.id String Required Immutable Identifier (UUID) of the user. Supplied in the endpoint.

    The one notification.template object applies a variant and locale to all three credential notification templates: credential_issued, credential_updated, and credential_revoked. When adding a variant or locale to any of the three notification templates, consider adding the same variant or locale to the other notification templates. If a requested variant is not defined, the notification uses the default notification template. If a requested locale is not defined, the notification uses the user's preferred language or, if the user has no preferred language, the default language of the environment.

    Although notification.template is immutable, Update a User Credential can change notification.template on a specific credential for its life span.

    data object data model

    The data object can only be used for Credential Types where its management.mode is MANAGED. Individual fields in data can only be used where the corresponding credential type's metadata.fields.type is Alphanumeric Text. If the corresponding credential type's metadata.fields.value is valued, that value represents a default for the field and can be overridden in Create a User Credential or Update a User Credential API requests.

    The data object contains any number of keys, where the key is the title in metadata.fields that represents a specific attribute of the credential type required by the issuer. For example, an insurance company might have a metadata.fields.title of Medical Limitations and the corresponding data key would be Medical Limitations. These data fields must match the metadata.fields defined for the credential type in credentialType.id. For more information on fields, see the fields object in metadata object data model and the data types in fields.type types.

    Whether any given data.<field> is required or optional depends on the corresponding fields.required and fields.value in the metadata object of the credential type. A data.<field> is required when fields.required is true and no fields.value exists and optional when fields.required is false or when fields.value has a value.

    Provisioned Credentials data model (credential)

    This object is shared with digital wallets. It is returned only with Read One User Credential Wallets and Read One Digital Wallet Credentials. The former returns all digital wallets associated with the specified user credential, the latter returns all user credentials associated with the specified digital wallet.

    Property Type Required? Mutable? Description
    claimReference Object N/A Read-only The serialized JSON object used to create the ClaimReference object returned. This is needed to revoke an issued credential.
    createdAt DateTime N/A Read-only Date and time the credential was provisioned.
    credential.id String N/A Read-only Identifier (UUID) of the user credential associated with the provisioned credential.
    digitalWallet.id String N/A Read-only Identifier (UUID) of the digital wallet associated with the provisioned credential.
    environment.id String N/A Read-only Identifier (UUID) of the environment associated with the provisioned credential.
    expiresAt Date N/A Read-only The date that the provisioned credential expires. If this value is null, the provisioned credential never expires.
    id String N/A Read-only Identifier (UUID) of the provisioned credential.
    status String N/A Read-only Status of the provisioned credential.
    user.id String N/A Read-only Identifier (UUID) of the user associated with the provisioned credential.
    walletActions Object[] N/A Read-only Array of actions taken regarding the provisioned credential.
    walletActions.action String N/A Read-only Action taken regarding the provisioned credential; can be CREDENTIAL_ACCEPTED, CREDENTIAL_REJECTED, CREDENTIAL_REVOKED, or CREDENTIAL_DELETED.
    walletActions.occurredAt DateTime N/A Read-only Date and time that the action occurred.
    Response codes
    Code Message
    200 Successful operation.
    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.
    500 Unexpected server error.

    Create a User Credential

    Read All User Credentials

    Read One User Credential

    Read One User Credential Wallets

    Update a User Credential

    Revoke a User Credential

    Credential Verifications

    The Credential Verification service receives, and responds to, requests for credential verification using Decentralized Identity Foundation Java Web Token Verifiable Credentials Presentation Profile (DIF JWT-VC Profile). The profile uses such open standards as:

    • World Wide Web Consortium (W3C) Decentralized Identifiers (DID) for core architecture, data model, and representations

    • W3C Verifiable Credentials Data Model for the presentation data model

    • DIF Presentation Exchange for credential request

    • OpenID for Verifiable Presentations (OpenID4VP ID1) as the base protocol for transportation

    Use of these standards provides interoperability with any app that complies with DIF JWT-VC Profile.

    The service can also use PingOne native protocols. The PingOne native protocol only works with apps that use the PingOne Neo Native SDKs, which has more features but is restricted to only supported apps.

    Credential Verifications session data model

    Property Type Required? Mutable? Description
    _links.appOpenURL.href String N/A Read-only URL to use in a mobile browser to open a compatible wallet app, such as the PingOne Neo Sample App.
    _links.qr.href String N/A Read-only URL to return a QR code that, when evaluated, opens the compatible wallet app to this verification.
    _links.self.href String N/A Read-only URL to return this same response.
    applicationInstance.id String Required/Optional Immutable Identifier (UUID) of the application running the Wallet SDK on the user's device and registered with the service. When set and protocol is NATIVE, the service sends a push notification to the application instance using the settings of the digital wallet application.
    didMethod String Optional Immutable The decentralized identifier method to use during the credential verification session. Can be JWK, the default, or ION.
    digitalWalletApplication.id String Optional Immutable Identifier (UUID) of the customer's digital wallet app that interacts with the user's digital wallet. When set and protocol is NATIVE, the service uses the appOpenURL defined on the Digital Wallet App instead of shocard.pingone.com.
    errors Object[] N/A Read-only Array of objects representing errors recorded when attempting an action on a credential. See Credential Verifications errors object data model.
    id String N/A Read-only Identifier (UUID) of the credential verification session.
    issuerFilter.dids String[] Optional Immutable Array of unique Decentralized Identifiers (DID). Ignored if protocol is NATIVE. See the note following this table.
    issuerFilter.environmentIds String[] Optional Immutable Array of PingOne environment identifiers. See the note following this table.
    message String Optional Immutable A message shown to the user by the compatible wallet app to alert the user.
    notification Object Optional Immutable Contains notification information. When protocol is NATIVE and applicationInstance.id is set, permits administrators to customize their push notification.
    notification.template Object Optional Immutable Contains template parameters.
    notification.template.locale String Optional Immutable The ISO 2-character language code used for the notification; for example, en.
    notification.template.variables Object[] Required/Optional Immutable An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, see Dynamic variables.
    notification.template.variant String Optional Immutable The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, see Creating custom contents.
    protocol String Optional Immutable Protocol to use for verification; can be OPENID4VP or NATIVE. If not present, defaults to NATIVE.
    requestedCredentials Object[] Required Immutable Array of objects that contain the type of credentials to verify and the keys to return from the credential. See the important note following this table.
    requestedCredentials.keys String[] Optional Immutable Array of strings that identify the key names for selective disclosure to return from the credential.
    requestedCredentials.type String Required Immutable Type of credential to verify. Must be the name of a PingOne credential type issued by the credential issuer.
    status String N/A Read-only Status of the verification request; can be INITIAL, WAITING, VERIFICATION_SUCCESSFUL, VERIFICATION_FAILED, or VERIFICATION_EXPIRED.

    The digital wallet service uses the credential_verification notification template to send a push notification to a digital wallet when a Create Credential Verification Session (NATIVE - Push Notification) is created. The notification.template object can define a variant and locale for the notification, if needed.

    If issuerFilter.environmentIds is submitted, the service searches all listed environments for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

    If issuerFilter.dids is submitted and protocol is OPENID4VP, the service searches all listed decentralized identifiers (DID) for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

    This issuerFilter.dids typically contains decentralized identifiers for issuers that are not using PingOne Credentials for JWT-VC issuance. The service supports these three DID methods:

    Credential Verifications credential data data model

    Property Type Required? Mutable? Description
    _links.self.href String N/A Read-only URL to return this verification credential data.
    credentialData Object[] N/A Read-only Array of objects containing the data found on the credential.
    credentialData.data Object[] N/A Read-only Array of objects containing the name-value pairs found on the credential. If a credential has not yet been shared, status is INITIAL or WAITING, then returns as an empty array.
    credentialData.data.key String N/A Read-only Name of the key of a name-value pair found on the credential.
    credentialData.data.value String N/A Read-only Value of a name-value pair found on the credential.
    credentialData.issuerId String N/A Read-only Identifier (UUID) of the issuer of the credential verified in the format from the credential issuer.
    credentialData.issuerLogo String N/A Read-only Base64-encoded logo of the issuer of the credential.
    credentialData.issuerName String N/A Read-only Name of the issuer of the credential verified.
    credentialData.type String N/A Read-only Space-delimited list of the types of credential verified.
    credentialData.types String[] N/A Read-only Array of the types of credential verified.
    errors Object[] N/A Read-only Array of objects representing errors recorded when attempting an action on a credential. See Credential Verifications errors object data model.
    id String N/A Read-only Identifier (UUID) of the verification credential data.
    status String N/A Read-only Status of the verification request; can be INITIAL, WAITING, VERIFICATION_SUCCESSFUL, VERIFICATION_FAILED, or VERIFICATION_EXPIRED.

    Credential Verifications session data data model

    Property Type Required? Mutable? Description
    _links.appOpenURL.href String N/A Read-only URL to use in a mobile browser to open a compatible wallet app, such as the PingOne Neo Sample App.
    _links.qr.href String N/A Read-only URL to return a QR code that, when evaluated, opens the compatible wallet app to this verification.
    _links.self.href String N/A Read-only URL to return this verification session data.
    applicationInstance.id String N/A Read-only Identifier (UUID) of the application running the Wallet SDK on the user's device and registered with the service.
    errors Object[] N/A Read-only Array of objects representing errors recorded when attempting an action on a credential. See Credential Verifications errors object data model.
    id String N/A Read-only Identifier (UUID) of the verification session data.
    status String N/A Read-only Status of the verification request; can be INITIAL, WAITING, VERIFICATION_SUCCESSFUL, VERIFICATION_FAILED, or VERIFICATION_EXPIRED.
    verifiedData Object[] N/A Read-only Array of objects containing the data found on the credential.
    verifiedData.data Object[] N/A Read-only Array of objects containing the name-value pairs found on the credential. If a credential has not yet been shared, status is INITIAL or WAITING, then returns as an empty array.
    verifiedData.data.key String N/A Read-only Name of the key of a name-value pair found on the credential.
    verifiedData.data.value String N/A Read-only Value of a name-value pair found on the credential.
    verifiedData.metaData Object N/A Read-only Contains metadata associated with the credential.
    verifiedData.metaData.issuanceDate String N/A Read-only The date and time the credential was issued in ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ format (milliseconds optional).
    verifiedData.metaData.issuerId String N/A Read-only Identifier (UUID) of the issuer of the credential verified in the format from the credential issuer.
    verifiedData.metaData.issuerLogo String N/A Read-only Base64-encoded logo of the issuer of the credential.
    verifiedData.metaData.issuerName String N/A Read-only Name of the issuer of the credential verified.
    verifiedData.metaData.verificationStatus String N/A Read-only Verification status of the credential. Can be VALID or INVALID.
    verifiedData.type String N/A Read-only Space-delimited list of the types of credential verified.
    verifiedData.types String[] N/A Read-only Array of the types of credential verified.
    Credential Verifications errors object data model
    Property Type Required? Mutable? Description
    errors.code String N/A Read-only A code that indicates the error encountered by the service. See Credential Verifications error codes.
    errors.target String N/A Read-only The part of the credential that caused the error encountered by the service.
    errors.message String N/A Read-only A message that describes the error encountered by the service.

    Credential Verifications error codes

    Code Message
    REQUESTED_CREDENTIAL_MISSING One or more of the requested credential types is not included in the presentation from the user.
    REQUESTED_FIELD_MISSING One or more of the requested fields for one or more credential types is not included in the presentation from the user.
    INVALID_TOKEN The idToken presented by the user’s wallet is not valid (format or signature error).
    INVALID_CREDENTIAL One or more of the credentials presented by the user could not be validated. Many different errors can cause this. A more specific error is returned in the errors array of the Read Credential Verification Credential Data or Read Credential Verification Session Data response.
    UNEXPECTED_ERROR An unexpected error occurred during credential verification.

    Response codes

    Code Message
    200 Successful operation.
    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.
    500 Unexpected server error.

    Create Credential Verification Session (OPENID4VP)

    Create Credential Verification Session (NATIVE)

    Create Credential Verification Session (NATIVE - Push Notification)

    Read One Credential Verification Status

    Read Credential Verification Credential Data

    Read Credential Verification Session Data

    Delete Credential Verification Session

    PingOne Verify

    For a user to initiate an ID verification request, the client must obtain an ID verification transaction record from the ID verification service. The transaction record is created when a POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/verifyTransactions request is made.

    The transaction record acts as permission for the user to engage in the verification process. The user can then submit the necessary user ID information (such as a driver license or passport) for verification by the ID Validation service. The user can also send a self-image that the ID Validation service compares to the submitted identity document, to ensure the submitter is the person on the document, and checks for liveness, to prevent fraud.

    One of the challenges to identity proofing is getting high quality images from the user. Our Universal Capture frontends do the best quality verification they can, but it is still possible that the images will not pass the quality check of the identity proofing vendor. When images are taken during verification (such as submitting government documents, liveness checks, or selfies), retries can be permitted to obtain a satisfactory image for processing. The number of retries permitted, if any, are set on the Verify Policy. The user's Universal Capture interface, such as a mobile phone with an app using the PingOne Verify Native SDKs, and the verification service negotiate directly for retries when an unacceptable image is submitted and a retry is permitted. Interaction at the API level is not required.

    Once verified, the transaction record also acts as a tracking mechanism to identify the user provisioned using ID Validation. This information is logged with the transaction record by the ID Validation service when the transaction ID is received by the client.

    US-based Driver Licenses

    Document verification provides additional verification support with American Association of Motor Vehicle Administrators (AAMVA). AAMVA offers a service, Driver's License Data Verification (DLDV), for identity proofing and vetting driver license, identity cards, mobile driver license (mDL), and other secure credentials. Most states (43) and the District of Columbia participate in DLDV. No U.S. territories participate. The states that do not participate in DLDV are:

    • Alaska (under review)
    • California (SSA only)
    • Louisiana (SSA only)
    • Minnesota (SSA only)
    • New York (SSA only)
    • Pennsylvania (participates but requires written permission from the individual)
    • Utah (SSA only)

    SSA only indicates that only the Social Security Administration has access, not even other government agencies have access. SSA uses AAMVA for employment eligibility.

    Submitting state-issued driver's license or identity document to DLDV increases the accuracy of document authentication and also checks their validity by the state government. Accuracy and validity increase by comparing the biographic data, selfie, or both with the issuing government system of record, or another authoritative commercial system of record when the government system of record is unavailable. Results of DLDV checks are returned with the results of other checks in the Verification Metadata.

    Request groups

    The requests are grouped by endpoints for ease of use.

    Documentation Endpoint
    Verify policies /environments/{{envID}}/users/{{userID}}/verifyPolicies
    Verify transactions /environments/{{envID}}/users/{{userID}}/verifyTransactions
    Verify voice phrases /environments/{{envID}}/voicePhrases
    Verify reference data /environments/{{envID}}/users/{{userID}}/referenceData
    Verify identity record matching /environments/{{envID}}/users/{{userID}}/identityRecordMatching
    Verify documents /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/documents
    Verified data /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/verifiedData
    Verification metadata /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/metaData
    Verification metrics /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/appEvents
    Verification actions /environments/{{envID}}/users/{{userID}}/<action>

    Verify Policies

    With verify policies, you can:

    • Configure what is required to verify a user.
    • Configure parameters for verification, such as the number of one-time password (OTP) attempts and OTP expiration.

    You can create as many verify policies as needed to satisfy every verification scenario.

    Verify policies can perform any of eight checks:

    • Government identity document - Validate a government-issued identity document, which includes a photograph, and can optionally compare biographic data extracted from the government-issued identity document to biographic data provided by the client from their records

    • AAMVA - For US-based government identity documents, you can enable system of record verification using American Association of Motor Vehicle Administrators(AAMVA) Driver's License Data Verification (DLDV0 for environments in the North America region (licensed separately) on the governmentID configuration object

    • Facial comparison - Compare a self-image to a reference photograph, such as on a government ID or previously verified photograph

    • Liveness - Inspect a self-image for evidence that the subject is alive and not a representation, such as a photograph or mask, and that the image is not an injection attack, such as a 3D rendering or deep fake

    • Email - Receive a one-time password (OTP) on an email address and return the OTP to the service

    • Phone - Receive a one-time password (OTP) on a mobile phone and return the OTP to the service

    • Voice - Compare a voice recording to a previously submitted reference voice recording

    • Credentials - Verify a presented digital credential

    A verify policy defines which of the eight checks are performed for a verification transaction and configures the parameters of each check. The checks can be either required or optional. All checks are performed for every document type received regardless of whether any check fails. If a type is optional, then the transaction can be processed with or without the documents for that type. If the documents are provided for that type and the optional type verification fails, it will not cause the entire transaction to fail.

    Injection attack detection check (IAD) is performed automatically when liveness check is required, after the liveness check is performed. When face comparison is required or both face comparison and liveness are required, the following rules apply:

    1. If face comparison and liveness are required: Face comparison check is performed and liveness check is performed then IAD is performed. If data collection only is set, face comparison and liveness checks are skipped and only IAD is performed.

    2. If face comparison is required and liveness is not required: Face comparison check is performed and, if successful, IAD is performed regardless of the state of data collection only.

    3. If face comparison is not required and liveness is required: Liveness check is performed then IAD is performed. If data collection only is set liveness checks is skipped and IAD is performed.

    Available to a verify policy for any of the checks is the optional data collection only mode, when dataCollectionOnly is set to true (found in the transaction configuration object). In data collection only mode, the user submits all documents defined by the policy, but the service verifies none of them. Once submitted, you can retrieve the documents with Read All Verification Documents or Read One Verification Document.

    You assign one verify policy as the default policy. When you create a verification transaction, a verify policy identifier is preferred, but not required. If you create a verification transaction without a policy identifier, the default policy is applied. You cannot delete a policy set as the default policy, you must first assign a different policy as the default and then delete this policy. Use the Update Verify Policy request to change the default policy or use the Create Verify Policy to create a new default policy by setting its default to true. The initial default policy, provided by PingOne Verify, performs government identity document, facial comparison, and liveness checks.

    Verify policies also permit voice enrollment. Voice enrollment requires a verify policy that has enrollment set to true. When you prepare a voice enrollment, you Create Verify Transaction that references that verify policy with enrollment set to true. Subsequent voice verification requires a verify policy that has enrollment set to false. When you prepare a voice verification, you Create Verify Transaction that references that verify policy with enrollment set to false.

    Verify policy data model

    Property Type Required? Mutable? Description
    createdAt String N/A Read-only Date and time the verify policy was created
    default Boolean Optional Mutable Required as true to set this verify policy as the default policy for the environment; otherwise optional and defaults to false
    description String Optional Mutable Description displayed in PingOne Admin UI, 1-1024 characters
    email Object Optional Mutable email and phone configuration object
    environment.id String Required Immutable Ping environment identifier (UUID) for user
    facialComparison Object Optional Mutable facialComparison configuration object
    governmentId Object Optional Mutable governmentID configuration object
    id String N/A Read-only Policy identifier (UUID)
    liveness Object Optional Mutable liveness configuration object
    name String Required Mutable Name displayed in PingOne Admin UI
    phone Object Optional Mutable email and phone configuration object
    transaction Object Optional Mutable transaction configuration object
    updatedAt String N/A Read-only Date and time the verify policy was updated. Can be null.
    voice Object Optional Mutable voice configuration object

    governmentID configuration object

    The GOVERNMENT_ID configuration object includes BIOGRAPHIC_MATCHING in the policy (if biographic data is provided when the client creates a verify transaction), but results are returned separately in Verification Metadata.

    Property Type Required? Mutable? Description
    failExpiredId Boolean Optional Mutable Whether the Government ID verification fails when the document is expired
    inspectionType String Optional Mutable Determine whether document authentication is automated, manual, or possibly both. Can be AUTOMATIC, MANUAL, or STEP_UP. See notes following this table.
    provider.auto String Optional Mutable Provider to use for the automatic verification service; can be MITEK (the default) or VERIFF
    provider.manual String Optional Mutable Provider to use for the manual verification service; can be MITEK
    retry.attempts Integer Optional Mutable Number of retries permitted when submitting images. Must be 0 (no retries permitted) to 3.
    verify String Required Mutable Controls if Government ID verification is REQUIRED, OPTIONAL, or DISABLED
    verifyAamva Boolean Optional Mutable Whether AAMVA DLDV verification is enabled

    Options for inspectionType are:

    • AUTOMATIC invokes automated identification inspection only

    • MANUAL invokes manual identification inspection only (additional license required)

    • STEP_UP invokes automated identification inspection and, if that fails, invokes manual identification inspection (additional license required)

    If verify is set to DISABLED, inspectionType is optional and ignored if used.

    If inspectionType is not used, it defaults to the highest option available to the license capabilities in your environment. Similarly, availability of the options depend on the license capabilities of your environment. For example, if your environment is only licensed for automated identification inspection, then MANUAL and STEP_UP will not be available.

    facialComparison configuration object

    Property Type Required? Mutable? Description
    threshold String Required Mutable Threshold for successful facial comparison; can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).
    verify String Required Mutable Controls if facial comparison is REQUIRED, OPTIONAL, or DISABLED

    liveness configuration object

    The LIVENESS configuration object includes INJECTION_DETECTION in the policy, but results are returned separately in Verification Metadata.

    Property Type Required? Mutable? Description
    retry.attempts Integer Optional Mutable The number of times a user can retake a selfie if prior attempt fails due to photo quality issues. Possible values for selfie retry attempts are 0-3.
    threshold String Required Mutable Threshold for successful facial comparison; can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).
    verify String Required Mutable Controls if liveness check is REQUIRED, OPTIONAL, or DISABLED

    email and phone configuration object

    Property Type Required? Mutable? Description
    createMfaDevice Boolean Optional Mutable When enabled, PingOne Verify registers the email address or phone number with PingOne MFA as a verified MFA device
    otp Object Optional Mutable SMS/Voice/Email one-time password (OTP) configuration
    otp.
    attempts    		 Object Required Mutable OTP attempts configuration
    otp.
    attempts.
    count    		 Integer Required Mutable Count of OTP failures
    otp.
    deliveries    		 Object Required Mutable OTP delivery configuration
    otp.
    deliveries.
    coolDown.
    duration    		 Integer Required Mutable Cooldown duration configuration; can be 0-1800 seconds (0-30 minutes)
    otp.
    deliveries.
    coolDown.
    timeUnit    		 String Required Mutable Time unit of cooldown duration: SECONDS or MINUTES
    otp.
    deliveries.
    coolDown    		 Object Required Mutable Cooldown (waiting period between OTP attempts) configuration
    otp.
    deliveries.
    count    		 Integer Required Mutable Count of OTP deliveries
    otp.
    lifeTime    		 Object Required Mutable The length of time for which the OTP is valid
    otp.
    lifeTime.
    duration    		 Integer Required Mutable OTP duration configuration; can be 60-1800 seconds (1-30 minutes)
    otp.
    lifeTime.
    timeUnit    		 String Required Mutable Time unit of OTP duration configuration: SECONDS or MINUTES
    otp.
    notification    		 Object Required Mutable OTP notification template configuration; for more information about templates, see Notifications Templates
    otp.
    notification.
    templateName    		 String Required Mutable Name of the template to use to pass a one-time passcode; must be email_phone_verification
    otp.
    notification.
    variantName    		 String Optional Mutable Name of the template variant to use to pass a one-time passcode
    verify String Required Mutable Controls if email or phone verification is REQUIRED, OPTIONAL, or DISABLED

    The notification.variantName in the email and phone configuration objects can define a variant for the email_phone_verification notification submitted in notification.templateName, if needed. After receipt of a Create Verify Transaction request, the verification service uses an email_phone_verification notification template to send notice of the action taken to the user via email or SMS text.

    transaction configuration object

    In the verify transaction response is expiresAt. Transactions do not allow users an unlimited amount of time to submit verification data and complete the verify transaction. If the verify transaction is not completed before the expiresAt date and time, the transaction fails. If all required documents are collected but are still being processed when expiresAt is reached, document processing continues and the transaction either passes or fails based on the processing result. The default verify transaction timeout is 30 minutes from transaction creation.

    Furthermore, data collection is also time-constrained. (Data collected, such as the images of documents and images of the user ("selfies"), are required by the verification service.) Data collection time starts when the user initiates data collection using PingOne Verify web or native SDK. If required data are not submitted by the lesser of the data collection timeout and the time remaining before expiresAt, the transaction fails. The default data collection timeout is 15 minutes from the start of data collection.

    To understand the timeouts, particularly the data collection timeout, an example may help. Let us say that the verify transaction timeout is 30 minutes and the data collection timeout is 15 minutes. If the user does not begin data collection for 18 minutes, the data collection timeout becomes 12 minutes - the lesser of the data collection timeout (15 minutes) and the remaining time before expiresAt (12 minutes).

    You can create a new verify policy or update an existing verify policy to use different timeouts.

    Property Type Required? Mutable? Description
    dataCollection Object Optional Mutable Object for data collection timeout definition
    dataCollection.
    timeout    		 Object Required Mutable Object for data collection timeout
    dataCollection.
    timeout.
    duration    		 Integer Required Mutable Length of time before data collection timeout expires; can be 0-1800 seconds (0-30 minutes)
    dataCollection.
    timeout.
    timeUnit    		 String Required Mutable Time unit of data collection timeout; can be SECONDS or MINUTES
    dataCollectionOnly Boolean Optional Mutable When true, collects documents specified in the policy without determining their validity; defaults to false
    timeout Object Optional Mutable Object for transaction timeout
    timeout.
    duration    		 Integer Required Mutable Length of time before transaction timeout expires; can be 60-1800 seconds (1-30 minutes)
    timeout.
    timeUnit    		 String Required Mutable Time unit of transaction timeout; can be SECONDS or MINUTES

    If dataCollectionOnly is true, documents submitted by a user are retained and available from Verify Documents, but are not verified. Additionally, when the verification policy requires facialComparison configuration object or liveness configuration object, injection attack detection is still automatically performed.

    voice configuration object

    Property Type Required? Mutable? Description
    comparison.
    threshold    		 String Required Mutable Comparison threshold; can be LOW, MEDIUM, or HIGH
    enrollment Boolean Required Mutable Controls if the transaction performs voice enrollment (true) or voice verification (false)
    liveness.
    threshold    		 String Required Mutable Liveness threshold; can be LOW, MEDIUM, or HIGH
    referenceData Object Optional Mutable Object for configuration of reference data stored per user for voice verification
    referenceData.
    retainOriginalRecordings    		 Boolean Optional Mutable Controls if the service stores the original voice recordings; defaults to false
    referenceData.
    updateOnReenrollment    		 Boolean Optional Mutable Controls updates to user's voice reference data (voice recordings) upon user re-enrollment. If true, new data adds to existing data. If false, new data replaces existing data.
    referenceData.
    updateOnVerification    		 Boolean Optional Mutable Controls updates to user's voice reference data (voice recordings) upon user verification. If true, new data adds to existing data. If false, new voice recordings are not retained as reference data.
    textDependent Object Optional Mutable Object for configuration of text dependent voice verification
    textDependent.
    phrase.
    id    		 String Required Mutable Identifier (UUID) of the voice phrase to use
    textDependent.
    samples    		 Integer Required Mutable Number of voice samples to collect
    verify String Required Mutable Controls if voice verification is REQUIRED, OPTIONAL, or DISABLED

    Create Verify Policy

    Read All Verify Policies

    Read One Verify Policy

    Update Verify Policy

    Delete Verify Policy

    Verify Transactions

    For each verification attempt, all the necessary information is gathered in a transaction. The verifyTransactions endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions, receives all read, status, and control requests associated with the verification attempt.

    In the responses is the verificationStatus object, a list that indicates the verification types being verified by the service and the verification status of each step. The verification types are keys in the list and the verification status is the value in the list.

    The verification types for a verify transaction are determined from the verify policy.

    In the response is expiresAt. Transactions do not allow users an unlimited amount of time to submit verification data and complete the verify transaction. If the verify transaction is not completed before the expiresAt date and time, the transaction fails. If all required documents are collected but are still being processed when expiresAt is reached, document processing continues and the transaction either passes or fails based on the processing result. The default verify transaction timeout is 30 minutes from transaction creation.

    Furthermore, data collection is also time-constrained. (Data collected, such as the images of documents and images of the user ("selfies"), are required by the verification service.) Data collection time starts when the user initiates data collection using PingOne Verify web or native SDK. If required data are not submitted by the lesser of the data collection timeout and the time remaining before expiresAt, the transaction fails. The default data collection timeout is 15 minutes from the start of data collection.

    To understand the timeouts, particularly the data collection timeout, an example may help. Let us say that the verify transaction timeout is 30 minutes and the data collection timeout is 15 minutes. If the user does not begin data collection for 18 minutes, the data collection timeout becomes 12 minutes - the lesser of the data collection timeout (15 minutes) and the remaining time before expiresAt (12 minutes).

    You can create a new verify policy or update an existing verify policy to use different timeouts.

    Verify transaction data model

    Property Type Required? Mutable? Description
    callback Object Optional Immutable Object containing a callback target. The first time a transaction transitions to SUCCESS or FAIL (expired transactions are ignored when they transition to FAIL), the service makes one GET request to the URL with the expected headers.
    callback.headers Object Optional Immutable Object containing request header fields to include with the callback request. Can contain any number of key-value pairs where the key is a header field name and its value is the header field value, which cannot be null. Duplicate keys are not permitted.
    callback.url String Required Immutable The URL to which a callback is sent. Must use HTTPS protocol and be a valid URL.
    createdAt DateTime N/A Read-only Date and time the ID verification request was sent
    environment.id String Required Immutable PingOne environment identifier (UUID) for user
    expiresAt DateTime N/A Read-only Date and time the ID verification expires. A null value indicates it never expires.
    id String N/A Read-only Transaction identifier (UUID)
    qrUrl String N/A Read-only A link to retrieve a QR code image encoded with webVerificationUrl
    redirect Object Optional Mutable Contains the URL and user message for where users are redirected after document collection.
    requirements Object Optional Mutable Contains one or more objects that contain information used by the service: requirements object
    sendNotification Object Optional Mutable Endpoint to which notifications are sent: sendNotification object
    transactionStatus Object Required Immutable Status of the transaction: transactionStatus object
    updatedAt DateTime N/A Read-only Date and time the response was received by the identity provider; can be null
    user.id String Required Immutable Identifier (UUID) for the user submitting the verify transaction
    verifyPolicy.id String Optional Mutable Identifier (UUID) of the verify policy
    webVerificationCode String N/A Read-only A code used to identify a particular transition from the desktop web interface to the mobile web interface
    webVerificationUrl String N/A Read-only A link to continue the transition from the desktop web interface to the mobile web interface. See the note regarding query parameter options following this table.

    The webVerificationUrl has query parameter options:

    1. You can append a &dt=1 query parameter to webVerificationUrl. You can offer to redirect your users to a mobile or desktop browser-based verification. By default, on laptop or desktop browsers, you present to the user a page with the QR code to continue verification on their mobile device. A &dt=1 query parameter also permits verification on laptop or desktop browsers.

    2. Deprecated - This query parameter is replaced by message in the redirect object. You can append a &redirectMessage=<message> query parameter to webVerificationUrl, where <message> is an unquoted, URL-encoded text string. The message appears after document collection. For example: &redirectMessage=You%27ve%20successfully%20collected%20all%20document%2e%20Return%20to%20registration.

    3. Deprecated - This query parameter is replaced by url in the redirect object. You can append a &redirectUrl=<redirect URL> query parameter to webVerificationUrl, where <redirect URL> is a URL-encoded redirect URL. The redirect URL appears after document collection. For example: &redirectUrl=https%3A%2F%2Fhome.example.com%2Fs%2Fmembership.

    redirect object

    Used only in the request body of Create Verify Transaction and never returned by any API response.

    Property Type Required? Mutable? Description
    redirect.url String Required Mutable The redirect URL where the user is returned to after document collection
    redirect.message String Optional Mutable The message presented to the user after document collection but before redirecting to the redirect.url
    requirements object

    Biographic matching occurs when the Verify Policy includes governmentId and the Create Verify Transaction includes the optional biographic matching data requirements (given_name, family_name, name, address, and birth_date). If the client does not provide biographic matching data, the service performs the verifications required by the verify policy. If the client does provide biographic matching data, the service performs the verifications required by the verify policy and then compares the data extracted from the government identity document to the data provided by the client.

    Property Type Required? Mutable? Description
    address Object Optional Immutable Object containing an array of addresses; can contain value or options, but not both
    address.options String[] Required/Optional Immutable An array of addresses
    address.value String Required/Optional Immutable One address
    birth_date Object Optional Immutable Object containing the birth date; can contain value or options, but not both
    birth_date.options String[] Required/Optional Immutable An array of one birth date in YYYY-MM-DD format; more than one element is not supported.
    birth_date.value String Required/Optional Immutable One birth date in YYYY-MM-DD format
    email Object Optional Immutable Object containing an array of email addresses.
    email.options String[] Required Immutable Array of email addresses to send email one-time password to.
    family_name Object Optional Immutable Object containing the family name; can contain value or options, but not both
    family_name.options String[] Required/Optional Immutable An array of family names
    family_name.value String Required/Optional Immutable One family name
    given_name Object Optional Immutable Object containing given names; can contain value or options, but not both
    given_name.options String[] Required/Optional Immutable An array of given names
    given_name.value String Required/Optional Immutable One given name
    name Object Optional Immutable Object containing the full name (given name and family name); can contain value or options, but not both
    name.options String[] Required/Optional Immutable An array of full names
    name.value String Required/Optional Immutable One full name
    phone Object Optional Immutable Object containing a mobile phone number.
    phone.value String Required Immutable Mobile phone number to send SMS text one-time password (OTP) to. See the note regarding phone numbers following this table.
    referenceSelfie Object Required/Optional Immutable Object containing a reference self image. Required when, in the verify policy referenced by verifyPolicy.id (or the default verify policy), facialComparison.verify is REQUIRED and governmentID.verify is DISABLED. Otherwise, referenceSelfie is ignored.
    referenceSelfie.value String Required Immutable A Base64-encoded reference self image. Image must be JPEG format.

    When a phone number is needed, a valid phone number string must be provided in international format consisting of a leading plus sign, 1 to 3-digit country code, and 4 to 14-digit phone number, for example, +14155552671.

    Always include the country code in the value you provide for the phone parameter. Phone formats across the globe are constantly expanding and changing. If the country code is not included, issues might occur with message delivery.

    The following sample shows acceptable valid phone attribute formatting for the same number:

    +1.5125201234
+15125201234
+1.512.520.1234
+1 (512) 520-1234
    sendNotification object
    Property Type Required? Mutable? Description
    email String Optional Mutable The email address to send email verification notifications to
    phone String Optional Mutable The phone number to send SMS text verification notifications to. See the note regarding phone numbers following the requirements object table.
    results Object[] N/A Read-only Array of objects that contain the results of attempts to notify the user. Provided only in the response to Create Verify Transaction.
    results.error Object N/A Read-only Contains information regarding why a notification failed to send.
    results.error.code String N/A Read-only A short alphanumeric code identifying the error.
    results.error.details Object[] N/A Read-only Array of objects that contain details of the error as provided by the source of the error. Exact format varies by source.
    results.error.id String N/A Read-only Identifier (UUID) of the error message.
    results.error.message String N/A Read-only A textual message explaining the error.
    results.method String N/A Read-only Method used in the attempt to notify the user; can be EMAIL or SMS.
    results.notification.id String N/A Read-only Identifier (UUID) of the notification that was sent.
    results.sent Boolean N/A Read-only Whether the notification was successfully sent.
    transactionStatus object
    Property Type Required? Mutable? Description
    providerMessagesList Object Optional Immutable Present when one or more verification types fail
    providerMessagesList.messages Object Required Immutable Contains name-value pairs where name is the error code and value is a textual error description. Some error messages are listed in Verification error messages.
    providerMessagesList.providerId String Required Immutable A generic descriptor of the provider; can be ID_VALIDATION, Mitek, Amazon, IdFace, or IdVoice
    providerMessagesList.verificationType String Required Immutable Verification type to which the message applies; see Verification types
    status String Required Mutable Status of the transaction, an enumerated list
    verificationStatus Object Required Immutable Contains name-value pairs where name is a verification type and value is the status of the verification type, an enumerated list

    Transaction level status definitions

    Status Definition
    APPROVED_MANUALLY The administrator has decided to override the result of the verification. The service providers were unable to provide a positive response but the administrator was able to peruse the physical documents.
    APPROVED_NO_REQUEST The administrator perused the physical documents of the user and approved the request without the need for third party verification.
    FAIL All of the service providers have responded and some of the results are not positive. The transactionStatus object contains error messages.
    IN_PROGRESS The user scanned the QR code and submitted the data. The service prepares to submit the data to third party providers.
    INITIATED User has started collecting documents but has not sent them to the service to be processed.
    NOT_REQUIRED The administrator has decided that this user does not require to be verified.
    PARTIAL Some, but not all, service providers have responded. The service is waiting on responses from other providers.
    REQUESTED The transaction is initiated but user has not scanned the QR code or submitted the data.
    SUCCESS All of the service providers have responded and the result of the verification is positive from all providers.

    Verification types

    Verification type Definition
    EMAIL Verifies the user's email address by sending a one time password (OTP) and having the user send that to PingOne Verify.
    FACIAL_COMPARISON_GOVERNMENT_ID Accepts a new self-image (selfie) and compares it to the image on the government identity document.
    FACIAL_COMPARISON_REFERENCE_SELFIE Accepts a new selfie and a reference selfie and compares the two selfies.
    GOVERNMENT_ID Accepts a government-issued identity document, such as drivers license or passport, and verifies it with verification providers.
    LIVENESS Accepts a single selfie and checks it for liveness.
    PHONE Verifies the user's phone number by sending an OTP and having the user send that to PingOne Verify.
    VOICE_ENROLLMENT Performs voice enrollment with recordings provided by the user or by PingOne Verify's customer.
    VOICE_VERIFICATION Performs voice verification with 1 recording provided by the end user or by PingOne Verify's customer.

    Verification type level status definitions

    Status Definition
    DEPENDENCY_FAILED Another verification type already failed and this verification type is not being processed. For example, Government ID will not be verified if the Facial Comparison or Liveness check failed.
    DOCUMENT_COLLECTED Documents were collected but not processed.
    FAIL The verification type completed and the result is not positive. The transactionStatus object contains error message.
    IN_PROGRESS The user has submitted the data and the service will perform the verification type.
    MANUAL_INSPECTION For government ID only: Verification submitted for manual inspection.
    REQUESTED The verification type is requested but the user has not submitted the data.
    RETRYABLE The verification type completed but the image submitted is unacceptable. Retries are permitted, the retry count is less than the maximum, and the transaction has not timed out.
    SUCCESS The verification type completed and the result is positive.
    TRANSACTION_TIMED_OUT Transaction was not completed within the timeout period.

    Verification error messages

    Errors returned vary by vendor:

    Mitek errors
    API errors

    If the transaction receives an error for reason code 144, DOCUMENT_IMAGES_MISMATCH - Document images do not match input type, you can ask the user to retry taking a document image.

    Reason
    Code    		 Error Code Message
    100 INTERNAL_ERROR Internal Error
    101 NO_RECORD No record found
    102 VALIDATION_IN_PROGRESS Validation process has already been started
    103 MISSING_SHOCARD_ID Shocard Id is missing
    104 MISSING_PUBLIC_KEY App public key is not set
    105 MISSING_CLAIM Claim is missing
    106 LIMIT_EXCEEDED Exceeded number of validation requests
    107 INVALID_REQUEST Invalid Request
    108 MISSING_DATA Missing Shared data in request
    109 DECRYPTION_ERROR Error in decrypting data
    110 FACE_VALIDATION_ERROR Face validation failed
    111 DOCUMENT_VALIDATION_ERROR Document validation failed
    112 DOCUMENT_VALIDATION_MISSING_DATA_ERROR Document validation missing data
    113 DOCUMENT_VALIDATION_INTERNAL_ERROR Document validation internal error
    114 JSON_READ_ERROR JSON read error
    115 JSON_WRITE_ERROR JSON write error
    116 FAILED_GETTING_TRANS_STATUS Failed getting transaction status
    117 INVALID_TRANSACTION_STATE Invalid transaction state
    118 DOCUMENT_VALIDATION_PROVIDER_INTERNAL_ERROR Document validation provider internal error
    119 DOCUMENT_VALIDATION_PROCESSING_RESULT_ERROR Document validation processing result error
    120 VALIDATION_NOT_IN_REQUESTED_STATUS Validation status not in the REQUESTED STATUS
    121 ENVIRONMENT_COULD_NOT_BE_FOUND Could not find Environment
    122 VERIFICATION_CAPABILITIES_ERROR Environment does not have verification capabilities
    123 ORGANIZATION_COULD_NOT_BE_FOUND Could not find Organization
    124 ORGANIZATION_QUOTA_ERROR No organization quota
    125 ORGANIZATION_QUOTA_DATE_ERROR Current date is out of quota dates range
    126 MISSING_UNIQUE_TOKEN Missing/invalid unique token
    127 PUBLIC_KEY_NOT_EMPTY App public key has already been set
    128 VERIFY_STATUS_NOT_INITIATED verifyStatus not initiated
    129 VERIFY_STATUS_IS_DISABLED verifyStatus is disabled
    130 LIVENESS_VALIDATION_ERROR Liveness validation failed
    139 DUPLICATE_RECORD_ERROR There is an existing record
    140 VALIDATION_NOT_IN_THE_EXPECTED_STATUS Validation status not in the Expected STATUS
    141 DOCUMENT_AGENT_ASSIST_INTERNAL_ERROR Document agent assist internal error
    142 DOCUMENT_AGENT_ASSIST_RESULT_ERROR Document agent assist processing result error
    143 DOCUMENT_AGENT_ASSIST_REQUEST_ERROR Document agent assist processing result error
    144 DOCUMENT_IMAGES_MISMATCH Document images do not match input type
    145 DEPENDENCY_FAILED Verification not performed because a dependency failed
    146 TRANSACTION_TIMEOUT Transaction timeout exceeded
    147 DATA_COLLECTION_TIMEOUT Data collection timeout exceeded
    148 DATA_COLLECTION_ONLY_NOT_SUPPORTED Data collection only not supported
    149 EXPIRED_GOVERNMENT_ID Government ID is expired
    150 OTP_ATTEMPTS_EXCEEDED OTP attempts exceeded
    151 OTP_SESSION_EXPIRED OTP session expired
    152 OTP_DELIVERY_FAILED Failed to deliver OTP
    153 MISSING_VERIFY_CONFIG VerifyPolicy could not be found
    154 INVALID_PROVIDER_CREDENTIAL_KEY Invalid Credential Key
    155 VOICE_ENROLLMENT_FAILED Voice Enrollment failed
    156 VOICE_VERIFICATION_FAILED Voice Verification failed
    157 VOICE_ENROLLMENT_NOT_FOUND User has not enrolled in Voice verification
    158 VOICE_RECORDING_SPOOFED Voice recording liveness check failed
    159 VOICE_RECORDING_POOR_QUALITY Voice recording quality too poor
    160 VOICE_RECORDING_SPEECH_SHORT Voice recording speech length is too short
    161 VOICE_SAMPLES_DONT_MATCH Voice enrollment samples do not match
    162 VOICE_MATCH_SCORE_TOO_LOW Voice match score too low
    163 VOICE_RECORDING_CHANNEL_CONFLICT Voice recording channel conflict
    164 PHONE_VALIDATION_ERROR Phone validation failed
    Processing reasons for document verification (automated)

    If the transaction receives an error for reason codes marked Yes in the Retry column, you can ask the user to retry taking a document image.

    Reason
    Code    		 Message Description Retry
    200 Image quality check failed. The image has failed image quality check. Yes
    201 The image is not sharp. The image is out of focus. Yes
    202 The image has glare. Glare was found on the document preventing extraction or authentication. Yes
    203 The image is too dark. The image is too dark. Yes
    204 The document on the image is too small. The amount of the image that the document takes up is too small. Retake Image - Try changing from portrait to landscape mode or getting closer to the image. Yes
    205 The ID document could not be found. This can be caused by the image not showing all four corners of the document. Retake Image - Ensure all four sides of the document are visible. Yes
    206 The type of ID document could not be determined. The type of document could not be identified. This could be caused by a low quality image or it could be a document that is not supported. Yes
    208 Invalid Image Type The encoding of the image is incorrect. It is not in a format that Mitek is able to process. Take a new image in a supported format. Yes
    209 Image is too small The input image had a width or height less than 400 pixels. Take a larger image. Yes
    210 Image processing failed after resizing. The input image had a width or height greater than 2000 pixels and was resized. You will only receive this message if processing failed after resizing. Take a smaller image. Yes
    211 The authenticator could not run because the input image was missing The authenticator was not able to assess the document because the input image was missing. Ensure that at least one image of an identity document was captured and submitted in the service request. Yes
    212 The image quality of the authenticator input image was poor. The authenticator was not able to assess the document because the image quality was too poor. Have the consumer capture a better quality image. Yes
    500 The barcode could not be found. The document was classified as a type that contains a barcode but the barcode could not be found.
    501 The barcode could not be extracted. The barcode was found but could not be read.
    502 The barcode could not be parsed. The barcode was read but the resulting data was not in the expected format.
    503 The barcode could not be processed A problem was encountered when trying to process barcode extraction and parsing.
    510 No data could be extracted for this document. Data could not be extracted
    511 Data could not be extracted from the back of the document. Data could not be extracted from the back of the document.
    512 The front of the ID document could not be extracted. The front of the ID document could not be extracted.
    513 Document not supported for extraction The document may or may not be classified but it is currently not supported for extraction.
    520 Data extraction was performed, but the system didn't accept the results. The data was extracted, but did not pass our additional checks to ensure the extraction is accurate.
    600 The Enhanced Security Feature (ESF) was expected for this type of document and not found. The document should have contained an ESF feature but no ESF was found.
    601 Only part of the Enhanced Security Feature (ESF) was found; the ID document may have been altered. Only part of the Enhanced Security Feature (ESF) was found; the ID document may have been altered.
    602 Only part of the Enhanced Security Feature (ESF) was found; the ID document may have been altered. Only part of the Enhanced Security Feature (ESF) was found; the ID document may have been altered.
    603 The Enhanced Security Feature (ESF) was found but shows evidence of tampering. The Enhanced Security Feature (ESF) was found but shows evidence of tampering.
    610 The picture area could not be identified. The portrait on the document could not be located.
    611 The picture image quality is too low. the portrait image quality is loo low. Retake Image
    612 The picture image has poor exposure. The picture image has poor exposure. Retake Image
    620 No MRZ was found on the document. The document was expected to have an MRZ on it based on its classification but no MRZ could be found.
    621 The MRZ was detected but was not in the proper format. The MRZ was detected but was not in the proper format.
    630 The MRZ check digits are invalid. The MRZ check digits are invalid.
    650 The fields used to determine font consistency could not be extracted The fields used to determine font consistency did not return any extraction results
    660 The document does not have enough fields to perform data comparison Field comparison could not be performed because there were not enough fields on the document to perform a data comparison.
    680 The barcode could not be found or was only partially detected on the document. The PDF417 barcode, typically found on USA or Canadian driving licenses or ID cards, could not be detected.
    698 The authenticator took too long to process. The authenticator took longer to process than was allowed to ensure a quick Mobile Verify Auto response.
    699 The authenticator is not available for this document. This message is returned when an authenticity test was not applied to a document because the document doesn't have the necessary features or some design features prevent evaluation
    700 Unavailable due to scheduled maintenance AAMVA or the document's issuing jurisdiction is currently in a scheduled maintenance window. In order to avoid a billable event, this transaction was not submitted.
    701 Jurisdiction temporarily unavailable The document's issuing jurisdiction is currently unable to process transactions.
    702 Jurisdiction system error The document's issuing jurisdiction encountered an unknown error.
    703 Jurisdiction did not respond in a timely manner The document's issuing jurisdiction did not respond in a timely manner.
    801 Document is too close to the camera Document Liveness could not be performed, because the document is too close to the camera.
    802 Document is too close to the image border Document Liveness could not be performed, because the distance between document and image border is too small.
    803 Part of the document is not present in the image Document Liveness could not be performed, because a part of the document is not visible in the image.
    804 Document is not detected in the image Document Liveness could not be performed, because the document could not be detected in the image.
    805 Document size in the image is too small Document Liveness could not be performed, because the document size in the image is too small.
    806 Too many documents were detected in the image Document Liveness could not be performed, because there are multiple documents in the image.
    807 Document Liveness temporarily unavailable Document Liveness service did not respond in a timely manner.
    Selfie capture

    If the transaction receives an error for error codes marked Yes in the Retry column, you can ask the user to retry taking a selfie.

    Error Code Error Message Meaning Retry
    FACE_ANGLE_TOO_LARGE Facial out-of-plane rotation angle is extremely large Facial out-of-plane rotation angle is extremely large Yes
    FACE_CLOSE_TO_BORDER Face is too close to one or more borders Face is too close to one or more borders. May reduce the accuracy of spoofing detection because edges of face may not be seen Yes
    FACE_CROPPED Face is cropped Face is cropped. May reduce the accuracy of spoofing detection because edges of face may not be seen Yes
    FACE_IS_OCCLUDED Face is occluded There is occlusion of a face, which impacts the accuracy of liveness. This detection is designed to work with the medical masks that cover nose and mouth, other occlusions are not guaranteed. Occlusion detection has probabilistic nature and may have errors. The threshold setting for occlusion detection may be tuned by changing face_occlusion_threshold setting. Please refer to PAD Configuration in Docker section for more information. Yes
    FACE_NOT_FOUND Failed to detect face Face detector can't find face on image. Face detection has probabilistic nature and may have errors. It also has some sensitivity level and very small faces may be ignored. Yes
    FACE_TOO_CLOSE Face is too close to the camera A distance between face and image border is too small for preprocessing issues Yes
    FACE_TOO_SMALL Interpupillary distance is too small Facial area is not big enough for analysis. Interpupillary distance in pixels is below the configured value Yes
    Absolute face size is too small Facial area is not big enough for analysis. Absolute face size in pixels is below the configured value Yes
    Relative face size is too small Facial area is not big enough for analysis. The relative proportion of face size in the image is below the configured value Yes
    FAILED_TO_ALLOCATE Current vm.max_map_count limit is too low Memory allocation error
    FAILED_TO_PREDICT_LANDMARKS Failed to predict landmarks Landmarks prediction error
    FAILED_TO_PREPROCESS_IMAGE_WHILE_DETECT Face detection error Face detection error
    FAILED_TO_PREPROCESS_IMAGE_WHILE_PREDICT Failed to preprocess image for *** Liveness prediction error
    FAILED_TO_READ_IMAGE File decoding error File decoding error
    FAILED_TO_READ_MODEL Failed to read model Model deserializing error
    FAILED_TO_WRITE_IMAGE File encoding error File encoding error
    INVALID_CONFIG Field *** not found in config Configuration file deserializing error
    INVALID_FUSE_MODE Invalid fuse mode provided Invalid fuse mode provided
    INVALID_META Invalid OS value provided in meta, should be one of: UNKNOWN, DESKTOP, ANDROID, IOS Invalid facesdk::Meta value
    LICENSE_ERROR Some error occurred during license checking Some error occurred during license checking
    NO_SUCH_OBJECT_IN_BUILD Object *** not found Engine or backend is not supported by the build
    NULLPTR Empty image Nullptr provided
    TOO_MANY_FACES Too many faces detected Face detector found more than one face on image. Please, note, that very small faces may be ignored if they are below the sensitivity level.
    UNKNOWN JNI: unknown exception Unhandled exception in the code
    Veriff errors
    Reason
    Code    		 Message Retry
    105 Suspicious behavior No
    204 Poor image quality No
    504 Attempted deceit, device screen used No
    505 Attempted deceit, printout used No
    507 Presented document tampered, data cross reference No
    508 Presented document tampered, document similarity to specimen No
    602 Presented document type not supported Yes
    608 Document front missing Yes
    614 Document front not fully in frame Yes
    619 Document data not visible Yes
    621 Document annulled or damaged Yes
    625 Unable to collect surname Yes
    627 Unable to collect date of birth Yes
    628 Unable to collect issue date Yes
    629 Unable to collect expiry date Yes
    630 Unable to collect gender Yes
    631 Unable to collect document number Yes
    632 Unable to collect personal number Yes
    633 Unable to collect nationality Yes
    634 Unable to collect home address Yes
    644 Unable to collect Identificador de Ciudadano (INE) Yes
    645 Resubmit - Unable to collect OCR (IFE) Yes
    647 Document not recognized Yes
    648 Technical issues Yes
    653 Unable to collect residence permit type Yes
    654 Unable to collect driver's license number Yes

    Create Verify Transaction

    Read All Verify Transactions

    Read One Verify Transaction

    Update Verify Transaction

    Delete Verify Transaction

    Verify Identity Record Matching

    With the Verify Identity Record Matching service, you can submit any of name, given name, family name, birth date, or address from an unverified source amd corresponding values from one or more verified sources. The identityRecordMatching endpoint, /environments/{{envID}}/users/{{userID}}/identityRecordMatching, compares the unverified biographic data to the verified biographic data and returns a raw score and confidence level of the match.

    Verify identity record matching request data model

    Property Type Required? Mutable? Description
    probe Object Required Mutable Object containing the data submitted from the document to match. At least one property is required.
    probe.address String Required/Optional Mutable Address of the identity submitted from the document to match
    probe.birth_date String Required/Optional Mutable Birth date name of the identity submitted from the document to match
    probe.family_name String Required/Optional Mutable Family name of the identity submitted from the document to match
    probe.given_name String Required/Optional Mutable Given name of the identity submitted from the document to match
    probe.name String Required/Optional Mutable Name of the identity submitted from the document to match
    gallery Object Required Mutable Object containing the data submitted from source records to match. A property is required for each probe property submitted.
    gallery.address String Required/Optional Mutable Address of the identity submitted from the document to match
    gallery.address.expression String Required/Optional Mutable PingOne Expression Language (PEL) expression to retrieve the address value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, see PingOne expression language.
    gallery.address.options String[] Required/Optional Mutable Array of literal address values to match.
    gallery.address.value String Required/Optional Mutable Literal address value to match.
    gallery.birth_date String Required/Optional Mutable Birth date name of the identity submitted from the document to match
    gallery.birth_date.expression String Required/Optional Mutable PingOne Expression Language (PEL) expression to retrieve the birth_date value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, see PingOne expression language.
    gallery.birth_date.options String[] Required/Optional Mutable Array of literal birth_date values to match.
    gallery.birth_date.value String Required/Optional Mutable Literal birth_date value to match.
    gallery.family_name String Required/Optional Mutable Family name of the identity submitted from the document to match
    gallery.family_name.expression String Required/Optional Mutable PingOne Expression Language (PEL) expression to retrieve the family_name value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, see PingOne expression language.
    gallery.family_name.options String[] Required/Optional Mutable Array of literal family_name values to match.
    gallery.family_name.value String Required/Optional Mutable Literal family_name value to match.
    gallery.given_name String Required/Optional Mutable Given name of the identity submitted from the document to match
    gallery.given_name.expression String Required/Optional Mutable PingOne Expression Language (PEL) expression to retrieve the given_name value, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, see PingOne expression language.
    gallery.given_name.options String[] Required/Optional Mutable Array of literal given_name values to match.
    gallery.given_name.value String Required/Optional Mutable Literal given_name value to match.
    gallery.name String Required Required/Optional Mutable
    gallery.name.expression String Required/Optional Mutable PingOne Expression Language (PEL) expression to retrieve the name value to match, such as supply a literal value, reformat the source value, or combine source attributes. For more information on PEL, see PingOne expression language.
    gallery.name.options String[] Required/Optional Mutable Array of literal name values to match.
    gallery.name.value String Required/Optional Mutable Literal name value to match.

    Verify identity record matching response data model

    Property Type Required? Mutable? Description
    detailedResults.address String N/A Read-only Address of the identity.
    detailedResults.address.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.
    detailedResults.address.
    probeValue    		 String N/A Read-only Value of address found on the government ID of the identity.
    detailedResults.address.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.address.
    galleryValue    		 String N/A Read-only Value of address on reference records provided by the requester.
    detailedResults.birth_date String N/A Read-only Birth date of the identity in ISO 8601 YYYY-MM-DD format.
    detailedResults.birth_date.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.
    detailedResults.birth_date.
    probeValue    		 String N/A Read-only Value of birth date found on the government ID of the identity.
    detailedResults.birth_date.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.birth_date.
    galleryValue    		 String N/A Read-only Value of birth date on reference records provided by the requester.
    detailedResults.family_name String N/A Read-only Family name of the identity.
    detailedResults.family_name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.
    detailedResults.family_name.
    probeValue    		 String N/A Read-only Value of family name found on the government ID of the identity.
    detailedResults.family_name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.family_name.
    galleryValue    		 String N/A Read-only Value of family name on reference records provided by the requester.
    detailedResults.given_name String N/A Read-only Given name of the identity. Can optionally include middle name.
    detailedResults.given_name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.
    detailedResults.given_name.
    probeValue    		 String N/A Read-only Value of given name found on the government ID of the identity.
    detailedResults.given_name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.given_name.
    galleryValue    		 String N/A Read-only Value of given name on reference records provided by the requester.
    detailedResults.name String N/A Read-only Full name of the identity.
    detailedResults.name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service. Can be HIGH, MEDIUM, LOW, or NONE.
    detailedResults.name.
    probeValue    		 String N/A Read-only Value of name found on the government ID of the identity.
    detailedResults.name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.name.
    galleryValue    		 String N/A Read-only Value of name on reference records provided by the requester.
    overallWeightedResult String N/A Read-only Weighted result of all reviewed fields. Can be HIGH, MEDIUM, LOW, or NONE.
    overallWeightedScore Decimal N/A Read-only Weighted score of all reviewed fields. A decimal number between 0 and 1.

    A confidence of NONE occurs when rawScore is very low or when a governmentIdValue value is missing but its corresponding requirementsValue is valued.

    Submit Identity Record Match

    Verify Voice Phrases

    The service stores reference data about the user that is later used in verify transactions. For voice verification, an enrollment transaction is necessary to store voice reference data. The voice reference data is then used during voice verification. Voice verification cannot be performed for a user if enrollment has not been performed.

    Voice verification does not evaluate the spoken words and therefore is language-independent and can be text-independent when used with longer speech streams. For interactive voice enrollment or verification, between the service and a user's mobile device, the user reads aloud a voice phrase that is submitted to the service. Verify voice phrases are the phrases that the user reads aloud. For non-interactive voice enrollment and verification, longer voice recordings are submitted without specific phrases spoken.

    Some phrases are pre-defined by the service. However, customers can define their own, custom phrases.

    Voice phrases are a container with a name. The actual phrases to speak are in contents, where the content has a locale and the phrase to speak written in the language required by the locale. Pre-defined phrases have contents in the locales supported by PingOne in their products. Because they are only read by a native speaker, custom voice phrases can be any locale and written in any language or character set.

    To define a custom voice phrase:

    1. Create a custom voice phrase container to hold the localized contents.
    2. Create a custom voice phrase content with the locale and content.

    Verify voice phrase data model

    Property Type Required? Mutable? Description
    id String N/A Read-only Voice phrase identifier. For customer-defined phrases, a UUID. For pre-defined phrases, a string derived from displayName.
    environment.id String Required Immutable Ping environment identifier (UUID) for user
    displayName String Required Mutable Suggested text to show for this voice phrase on a user interface. Must be unique within the environment identified by environment.id.
    createdAt DateTime N/A Read-only This field records the date and time the verify phrase was created
    updatedAt DateTime N/A Read-only This field records the date and time the verify phrase was updated; can be null

    Verify voice phrase contents data model

    Property Type Required? Mutable? Description
    id String N/A Read-only Voice phrase identifier. For customer-defined phrases, a UUID. For pre-defined phrases, a string derived from displayName.
    environment.id String Required Immutable Ping environment identifier (UUID) for user
    voicePhrase.id String Required Immutable Identifier (UUID) for the voice phrase for which this is contents
    locale String Required Mutable Locale for content
    content String Required Mutable Phrase users must speak and write in the language specified by locale
    createdAt DateTime N/A Read-only This field records the date and time the verify policy was created
    updatedAt DateTime N/A Read-only This field records the date and time the verify policy was updated; can be null

    Create Custom Voice Phrase

    Create Custom Voice Phrase Content

    Read All Voice Phrases

    Read All Voice Phrase Contents

    Read One Voice Phrase

    Read One Voice Phrase Content

    Update Custom Voice Phrase

    Update Custom Voice Phrase Content

    Delete Custom Voice Phrase

    Delete Custom Voice Phrase Content

    Verify Reference Data

    Verify reference data is any data submitted by the user, or by a PingOne customer on behalf of the user, to the verification service as reference material for later comparison during verification. Reference data are voice samples. Verify reference data is retained for an indefinite period of time, although it can be deleted.

    Verify reference data data model

    Note: The data property can contain rather large base64-encoded data. To reduce message size, it is not returned by Read All Reference Data. Use that call to find the id of a specific reference data and then use Read One Reference Data to retrieve it.

    Property Type Required? Mutable? Description
    id String N/A Read-only Reference data identifier (UUID or textual descriptor)
    environment.id String Required Immutable Ping environment identifier (UUID) of the user
    user.id String Required Immutable Identifier (UUID) for the user
    type String Required Immutable The type of reference data represented; can be VOICE
    data Object Required Mutable User's reference data: data object
    createdAt DateTime N/A Read-only Date and time the reference data was created
    updatedAt DateTime N/A Read-only Date and time the reference data was updated; can be null

    data object

    Note: The data object can contain rather large base64-encoded data and therefore is returned only with Read One Reference Data. To find the id for specific reference data, use Read All Reference Data and find the 'id of the reference data to retrieve.

    Property Type Required? Mutable? Description
    voiceRecordings Object[] Optional Mutable Array of voice recording objects
    voiceRecordings.id String N/A Read-only Voice recording identifier (UUID)
    voiceRecordings.recording String Required Mutable Base64-encoded voice recording submitted
    voiceRecordings.channel String Required Mutable Source of the voice recording submitted; can be MIC (from user's mobile device microphone) or TEL (from a recorded telephone call with the user)
    voiceRecordings.createdAt DateTime N/A Read-only Date and time the voice recording was created
    voiceRecordings.updatedAt DateTime N/A Read-only Date and time the voice recording was updated; can be null
    voiceTemplates Object[] Required Mutable Array of voice template (created from the voice recordings) objects
    voiceTemplates.id String N/A Read-only Voice template identifier (UUID)
    voiceTemplates.template String Required Mutable Base64-encoded voice template extracted from a submitted recording
    voiceTemplates.mergedTemplate Boolean Required Mutable Whether new templates should be merged into existing templates to adapt to the user’s voice changes over time
    voiceTemplates.channel String Required Mutable Source of the voice template submitted; can be MIC (from user's mobile device microphone) or TEL (from a recorded telephone call with the user)
    voiceTemplates.
    voiceSdkVersion    		 Object N/A Read-only Information regarding the SDK used to create the template
    voiceTemplates.
    voiceSdkVersion.version    		 String N/A Read-only Version of the SDK
    voiceTemplates.
    voiceSdkVersion.initializationDataId    		 String N/A Read-only Identifier of the initialization data
    voiceTemplates.
    voiceSdkVersion.algorithm    		 String N/A Read-only Algorithm used
    voiceTemplates.sourceTemplateIds String[] Optional Mutable Array of voice template identifiers (UUIDs) of the voice templates merged into this template when voiceTemplates.mergedTemplate is true
    voiceTemplates.createdAt DateTime N/A Read-only Date and time the voice template was created
    voiceTemplates.updatedAt DateTime N/A Read-only Date and time the voice template was updated; can be null
    voicePhraseContent Object N/A Read-only Voice phrase content used to create the reference data; see Verify voice phrase contents data model
    createdAt DateTime N/A Read-only Date and time the voice recording was created
    updatedAt DateTime N/A Read-only Date and time the voice recording was updated; can be null

    Read All Reference Data

    Read One Reference Data

    Delete All Reference Data

    Delete One Reference Data

    Verify Documents

    For each verification transaction, you can read documents (such as the images of documents and images of the user, "selfies") submitted to the transaction for a short time. The documents endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/documents, receives all requests for documents associated with the verification transaction. This endpoint returns the data regardless of whether the transaction is ever submitted for verification.

    Only those with an Identity Data Admin role are permitted to use the documents endpoint.

    Documents are retained for 30 minutes after creating or updating the document (submitted with the requests Create Verification Document or Update Verification Document or collected by the end user in the Universal Capture frontend) or until manually deleted with Delete Verification Document. Until removed, any number of GET or PUT requests to the documents endpoint can be successfully performed.

    All verify documents data model

    When all verify documents for a verification transaction are requested, the verify document for each verification type of the most recent retry appears in a documents array in the response. The verify document data model for each verification type of earlier retries appear in a previousAttempts array in the response.

    Property Type Required? Mutable? Description
    _embedded Object N/A Read-only Container for returned data.
    documents Object[] N/A Read-only Array of verifiedData objects for each verification type for the most recent verification attempt.
    previousAttempts Object[] N/A Read-only Array of verifiedData objects for each verification type for unacceptable verification attempts.
    size Integer N/A Read-only The number of objects returned in documents.

    Specific verify document data model

    When specific verify document for a verification type within a verification transaction are requested, the verify document data model appears as the response, regardless of which retry attempt it is.

    Verify document data model

    Property Type Required? Mutable? Description
    id String N/A Read-only Document identifier (UUID)
    retry.attempt Integer N/A Read-only Number of the retry attempt when submitting images.
    source.provider String Required Immutable Provider of the documents. Can be END_USER, AUTHENTICATED_CLIENT.
    status String N/A Read-only Status of the document. Can be COLLECTED or PROCESSED.
    type String Required Immutable Type of document in value. See Document types and values.
    value String Required Immutable Document, for the format of the document see Document types and values

    Document types and values

    Document Type Value
    Document Back Base64 encoded JPEG
    Document Front Base64 encoded JPEG
    Driver License Back Base64 encoded JPEG
    Driver License Code decoded text from the PDF417 barcode
    Driver License Front Base64 encoded JPEG
    Email textual email address
    Passport Card Back Base64 encoded JPEG
    Passport Card Front Base64 encoded JPEG
    Passport Front Base64 encoded JPEG
    Phone textual phone number
    Selfie Base64 encoded JPEG
    Voice Input Base64 encoded LPCM WAV voice recording submitted for verification
    Voice Sample Base64 encoded LPCM WAV voice recording submitted for enrollment

    Note: Voice recordings must be sampled at 16 KHz when submitted from reading voice phrases or at 8 KHz when submitted from longer, text-independent recordings.

    Create Verification Document

    Process Verification Documents

    Complete Verification Documents

    Read All Verification Documents

    Read One Verification Document

    Update Verification Document

    Delete Verification Document

    Verified Data

    For each verification attempt, you can read data submitted in the transaction for a short time. The verifiedData endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/verifiedData, receives all requests for data associated with the verification attempt.

    Only those with an Identity Data Admin role are permitted to use the verifiedData endpoint.

    User's verification data are retained for 30 minutes after a verification decision is made. Until removed, any number of requests to the verifiedData endpoint can be successfully performed.

    A note on extracted data

    Identity document verification uses two methods to extract personally identifiable information (PII): barcodes and optical character recognition (OCR).

    If the identity document has a barcode, PII is extracted from it. Barcodes are designed to enhance the reliability of data extraction and have error rates of fewer than 1 in a million. Barcodes are on all US driver licenses, but on few other identity documents.

    OCR is most commonly used to extract PII. With OCR, the scanner attempts to recognize the individual characters and words on the image of the identity document and convert them to a digital representation of that character or word. With optimized sources, OCR can achieve error rates as low as 1 in 10,000. However, error rates with non-optimized images often exceed 1 in 100. Identity documents captured by smartphone cameras often suffer from poor focus, skew, low contrast, or too-low or too-high illumination that make effective OCR difficult.

    It is important to note that, unless licensed for AAMVA checks for US driver licenses, PII extracted from identity document images is not checked against a system of record. That is, the verification service can show that the holder of the identity document matches the portrait on the identity document, but it does not show that the PII on the identity document is true or accurate.

    All verified data data model

    When all verified data for a verification transaction are requested, the verified data for each verification type of the most recent retry appears in a verifiedData array in the response. The verified data data model for each verification type of earlier retries appear in a previousAttempts array in the response.

    Property Type Required? Mutable? Description
    _embedded Object N/A Read-only Container for returned data.
    verifiedData Object[] N/A Read-only Array of verifiedData objects for each verification type for the most recent verification attempt.
    previousAttempts Object[] N/A Read-only Array of verifiedData objects for each verification type for unacceptable verification attempts.
    size Integer N/A Read-only The number of objects returned in verifiedData.

    Specific verified data data model

    When specific verified data for a verification type within a verification transaction are requested, the verified data data model appears as the response, regardless of which retry attempt it is.

    verified data data model

    Property Type Required? Mutable? Description
    data Object N/A Read-only Verification data for GOVERNMENT_ID, BARCODE, BIOGRAPHIC_MATCH, VOICE_SAMPLE, VOICE_INPUT, END_USER_CLIENT, and all other types
    id String N/A Read-only Transaction identifier (UUID)
    retry.attempt Integer N/A Read-only Number of the retry attempt when submitting images.
    type String Required Immutable The type of personally identifiable information (PII) in the object. Can be GOVERNMENT_ID, BARCODE, FRONT_IMAGE, BACK_IMAGE, SELFIE, CROPPED_SIGNATURE, CROPPED_DOCUMENT, CROPPED_PORTRAIT, VOICE_SAMPLE, VOICE_INPUT, END_USER_CLIENT, or BIOGRAPHIC_MATCH.

    data object for type = GOVERNMENT_ID

    Property Type Required? Mutable? Description
    addressCity String N/A Read-only The city in the address
    addressFull String N/A Read-only The complete address as discovered (Veriff only)
    addressHouseNumber String N/A Read-only The street number in the address (Veriff only)
    addressState String N/A Read-only The state or province in the address
    addressStreet String N/A Read-only The street in the address
    addressZip String N/A Read-only The postal code in the address
    birthDate String N/A Read-only The birth date in YYYY-MM-DD format of the identity
    country String N/A Read-only The country in the address (Mitek only)
    documentNumber String N/A Read-only The identification number of the identity document (Veriff only)
    expirationDate String N/A Read-only The expiration date in YYYY-MM-DD format of the identity document
    firstName String N/A Read-only The first name of the identity. Can optionally include middle name.
    gender String N/A Read-only The gender of the identity. Used only with agent assisted flows.
    idNumber String N/A Read-only The identification number of the identity document (Mitek only)
    idType String[] Required Immutable Array of the types of personally identifiable information (PII) submitted, such as DriversLicenseFront or RESIDENCE_PERMIT
    issueDate String N/A Read-only The issue date in YYYY-MM-DD format of the identity document
    issuingCountry String N/A Read-only The country of the document issuer
    lastName String N/A Read-only The last name of the identity
    nationality String N/A Read-only The nationality of the identity. Used only with agent assisted flows. (Mitek only)
    weight String N/A Read-only The confidence weight of the identity. Used only with agent assisted flows. (Mitek only)

    data object for type = BARCODE

    Property Type Required? Mutable? Description
    PDF417 String N/A Read-only The data parsed off the barcode of a drivers license

    data object for type = BIOGRAPHIC_MATCH

    Property Type Required? Mutable? Description
    detailedResults.address String N/A Read-only Address of the identity.
    detailedResults.address.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.address.
    governmentIdValue    		 String N/A Read-only Value of address found on the government ID of the identity.
    detailedResults.address.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.address.
    requirementsValue    		 String N/A Read-only Value of address on reference records provided by the requester.
    detailedResults.birth_date String N/A Read-only Birth date of the identity in ISO 8601 YYYY-MM-DD format.
    detailedResults.birth_date.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.birth_date.
    governmentIdValue    		 String N/A Read-only Value of birth date found on the government ID of the identity.
    detailedResults.birth_date.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.birth_date.
    requirementsValue    		 String N/A Read-only Value of birth date on reference records provided by the requester.
    detailedResults.family_name String N/A Read-only Family name of the identity.
    detailedResults.family_name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.family_name.
    governmentIdValue    		 String N/A Read-only Value of family name found on the government ID of the identity.
    detailedResults.family_name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.family_name.
    requirementsValue    		 String N/A Read-only Value of family name on reference records provided by the requester.
    detailedResults.given_name String N/A Read-only Given name of the identity. Can optionally include middle name.
    detailedResults.given_name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.given_name.
    governmentIdValue    		 String N/A Read-only Value of given name found on the government ID of the identity.
    detailedResults.given_name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.given_name.
    requirementsValue    		 String N/A Read-only Value of given name on reference records provided by the requester.
    detailedResults.name String N/A Read-only Full name of the identity.
    detailedResults.name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.name.
    governmentIdValue    		 String N/A Read-only Value of name found on the government ID of the identity.
    detailedResults.name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.name.
    requirementsValue    		 String N/A Read-only Value of name on reference records provided by the requester.
    overallWeightedResult String N/A Read-only Weighted result of all reviewed fields as described in Biographic match results match definitions.
    overallWeightedScore Decimal N/A Read-only Weighted score of all reviewed fields. A decimal number between 0 and 1.

    Biographic match results match definitions

    Value Description
    HIGH Based on a threshold, the quality of the match indicates that the match is an exact match or can be qualified as a near-exact match.
    MEDIUM Based on a threshold, the quality of the match is not exact but can be qualified as a partial match or an alternate spelling for the same value.
    LOW Based on a threshold, the quality of the match cannot be qualified as exact, near-exact, partial, or misspelled.
    NONE A raw score was so low that we have no confidence in a match.
    NOT_APPLICABLE A value was not found in the processed document for the given identifier. For example, the user is required to supply an address but the document supplied, such as a passport, does not have an address.

    data object for type = FRONT_IMAGE, BACK_IMAGE, SELFIE, CROPPED_SIGNATURE. CROPPED_DOCUMENT, and CROPPED_PORTRAIT

    Property Type Required? Mutable? Description
    FORMAT String N/A Read-only The format of the image, typically JPEG
    IMAGE String N/A Read-only The Base64-encoded image

    data object for type = VOICE_SAMPLE

    Available after voice enrollment.

    Property Type Required? Mutable? Description
    recordings Object[] N/A Read-only Array of objects of voice enrollment samples
    recordings.channel String N/A Read-only Channel through which the recording was submitted. Can be MIC or TEL.
    recordings.createdAt DateTime N/A Read-only Date and time when the voice enrollment sample was submitted
    recordings.id String N/A Read-only Identifier (UUID) of the voice enrollment sample
    recordings.recording String N/A Read-only Base64 encoded LPCM WAV voice enrollment sample
    recordings.textDependent Boolean N/A Read-only Whether or not the voice enrollment sample was read from a fixed phrase

    data object for type = VOICE_INPUT

    Available after voice verification.

    Property Type Required? Mutable? Description
    recordings Object[] N/A Read-only Array of objects of voice verification samples
    recordings.channel String N/A Read-only Channel through which the recording was submitted. Can be MIC or TEL.
    recordings.createdAt DateTime N/A Read-only Date and time when the voice verification sample was submitted
    recordings.id String N/A Read-only Identifier (UUID) of the voice verification sample
    recordings.recording String N/A Read-only Base64 encoded LPCM WAV voice verification sample
    recordings.textDependent Boolean N/A Read-only Whether or not the voice verification sample was read from a fixed phrase

    data object for type = END_USER_CLIENT

    Property Type Required? Mutable? Description
    ipAddress String N/A Read-only The IP address, version 4 or 6, of the device that performs the verification
    userAgent String N/A Read-only The HTTP user agent of the device that performs the verification

    Verified data portrait background data model

    This data model applies to Update Verified Data Portrait Background to replace the background of a self portrait (selfie) with a background of a uniform color defined in the backgroundColor object.

    Property Type Required? Mutable? Description
    backgroundColor Object Required Immutable Color of the replacement background as an RGB color mode.
    red Integer Required Immutable Value of RED in the range 0-255.
    green Integer Required Immutable Value of GREEN in the range 0-255.
    blue Integer Required Immutable Value of BLUE in the range 0-255.
    aspectRatio Object Required Immutable An object that represents an aspect ratio between 1/30 and 30. Both integers are required.
    aspectHeight Integer Required Immutable Value of the height in the aspect ratio in the range 1-1000.
    aspectWidth Integer Required Immutable Value of the width in the aspect ratio in the range 1-1000.

    Read All User Verified Data

    Read One User Verified Data

    Update Verified Data Portrait Background

    Delete All User Verified Data

    Delete One User Verified Data

    Verification Metadata

    For each verification attempt, you can retrieve all scores in the transaction returned from verification services. The metaData endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/metaData, receives all requests for scores associated with the verification attempt and returned from verification services.

    Only those with an Identity Data Admin role are permitted to use the metaData endpoint.

    All verification metaData data model

    When all metadata for a verification transaction are requested, the verification metadata for each verification type of the most recent retry appears in a metaData array in the response. The verification metaData data model for each verification type of earlier retries appear in a previousAttempts array in the response.

    Property Type Required? Mutable? Description
    _embedded Object N/A Read-only Container for returned data.
    metaData Object[] N/A Read-only Array of verification metaData objects for each verification type for the most recent verification attempt.
    previousAttempts Object[] N/A Read-only Array of verification metaData objects for each verification type for unacceptable verification attempts.
    size Integer N/A Read-only The number of objects returned in metaData.

    Specific verification metaData data model

    When specific metadata for a verification type within a verification transaction are requested, the verification metaData data model appears as the response, regardless of which retry attempt it is.

    Verification metaData data model

    Property Type Required? Mutable? Description
    data Object N/A Read-only Data object data model.
    id String N/A Read-only Identifier (UUID) of the transaction metadata.
    provider String N/A Read-only The provider of metadata in the object. Can be: AMAZON, BABEL_STREET, BIOGRAPHIC_MATCHER, IDRND, or MITEK.
    retry.attempt Integer N/A Read-only Number of the retry attempt when submitting images.
    status String N/A Read-only Status of the check. Can be SUCCESS or FAIL.
    type String N/A Read-only The type of metadata in the object. Can be: FACIAL_COMPARISON, BIOGRAPHIC_MATCH, INJECTION_DETECTION, LIVENESS, VOICE_ENROLLMENT, VOICE_VERIFICATION, DOCUMENT_AUTHENTICATION, DOCUMENT_MANUAL_AUTHENTICATION, or AAMVA.

    data object data model

    The data object in verification metadata varies depending on the values of type and provider as seen in the table.

    Type Provider Data model
    FACIAL_COMPARISON AMAZON data model
    BIOGRAPHIC_MATCH BABEL_STREET data model
    BIOGRAPHIC_MATCH BIOGRAPHIC_MATCHER data model
    INJECTION_DETECTION IDRND data model
    LIVENESS IDRND data model
    VOICE_ENROLLMENT IDRND data model
    VOICE_VERIFICATION IDRND data model
    DOCUMENT_AUTHENTICATION MITEK data model
    DOCUMENT_AUTHENTICATION VERIFF data model
    DOCUMENT_MANUAL_AUTHENTICATION MITEK data model
    AAMVA MITEK data model

    data object for FACIAL_COMPARISON + AMAZON

    Property Type Required? Mutable? Description
    confidence Double N/A Read-only A float between 0 and 100 that represents the level of confidence that the image contains a face.
    quality.
    brightness    		 Double N/A Read-only A float between 0 and 100 that represents the brightness of the face. A higher value indicates a brighter face image.
    quality.
    sharpness    		 Double N/A Read-only A float between 0 and 100 that represents the sharpness of the face. A higher value indicates a sharper face image.
    similarity Double N/A Read-only A float between 0 and 100 that represents the level of confidence that the faces match.

    data object for BIOGRAPHIC_MATCH + BABEL_STREET

    While GOVERNMENT_ID configuration includes BIOGRAPHIC_MATCH in Verify Policies, results are returned separately in verification metadata.

    Property Type Required? Mutable? Description
    detailedResults.address String N/A Read-only Address of the identity.
    detailedResults.address.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.address.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.birth_date String N/A Read-only Birth date of the identity in ISO 8601 YYYY-MM-DD format.
    detailedResults.birth_date.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.birth_date.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.family_name String N/A Read-only Family name of the identity.
    detailedResults.family_name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.family_name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.given_name String N/A Read-only Given name of the identity. Can optionally include middle name.
    detailedResults.given_name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.given_name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    detailedResults.name String N/A Read-only Full name of the identity.
    detailedResults.name.
    confidence    		 String N/A Read-only Confidence level of the match returned by the service as described in Biographic match results match definitions.
    detailedResults.name.
    rawScore    		 String N/A Read-only Raw numeric score returned by the service. Ranges from 0 to 1.
    overallWeightedResult String N/A Read-only Weighted result of all reviewed fields as described in Biographic match results match definitions.
    overallWeightedScore Decimal N/A Read-only Weighted score of all reviewed fields. A decimal number between 0 and 1.
    Biographic match results match definitions
    Value Description
    HIGH Based on a threshold, the quality of the match indicates that the match is an exact match or can be qualified as a near-exact match.
    MEDIUM Based on a threshold, the quality of the match is not exact but can be qualified as a partial match or an alternate spelling for the same value.
    LOW Based on a threshold, the quality of the match cannot be qualified as exact, near-exact, partial, or misspelled.
    NONE A raw score was so low that we have no confidence in a match.
    NOT_APPLICABLE A value was not found in the processed document for the given identifier. For example, the user is required to supply an address but the document supplied, such as a passport, does not have an address.

    data object for BIOGRAPHIC_MATCH + BIOGRAPHIC_MATCHER

    While GOVERNMENT_ID configuration includes BIOGRAPHIC_MATCH in Verify Policies, results are returned separately in verification metadata.

    Property Type Required? Mutable? Description
    biographic_match_results Object[] N/A Read-only Array of objects containing the results
    biographic_match_results.
    identifier    		 String N/A Read-only Attribute that was checked. Can be address, birth_date, family_name, given_name, or name.
    biographic_match_results.
    match    		 String N/A Read-only Relative indicator of success as described in Biographic match results match definitions

    data object for INJECTION_DETECTION + IDRND

    While LIVENESS configuration includes INJECTION_DETECTION in Verify Policies, results are returned separately in verification metadata.

    Property Type Required? Mutable? Description
    probability Double N/A Read-only A float, either 0.0 or 1.0, that represents the probability of no injection attacks in the image.

    data object for LIVENESS + IDRND

    Property Type Required? Mutable? Description
    probability Double N/A Read-only A float between 0 and 1 that represents the liveness probability of the image.
    quality Double N/A Read-only A float between 0 and 1 that represents the quality of the image.
    score Double N/A Read-only A float that represents the raw liveness score. A higher value means more alive.

    data object for VOICE_ENROLLMENT + IDRND

    Available with voice enrollment.

    Property Type Required? Mutable? Description
    recordingComparisons Object[] N/A Read-only Array of objects of voice enrollment comparisons between pairs of samples.
    recordingComparisons.
    probability    		 Double N/A Read-only A float between 0 and 1 that represents the comparison probability of the voice enrollment sample.
    recordingComparisons.
    score    		 Double N/A Read-only A float that represents a raw comparison score, intended to be used for evaluation and data calibration. A higher value means more closely matched voice enrollment samples.
    recordingComparisons.
    voiceTemplateIds    		 String[] N/A Read-only Array of identifiers (UUIDs) of the voice templates (a construct that contains the uniquely identifying biological characteristics of a person’s voice) for the voice enrollment samples compared.
    recordings Object[] N/A Read-only Array of objects of voice enrollment samples.
    recordings.antispoof.probability Double N/A Read-only A float between 0 and 1 that represents the probability that the voice enrollment sample is not a spoofed recording.
    recordings.antispoof.
    score    		 Double N/A Read-only A float that represents a raw comparison score, intended to be used for evaluation and data calibration. A higher value means the voice enrollment sample is less likely a spoofed recording.
    recordings.antispoof.
    unsuitable_input_message    		 Boolean N/A Read-only Whether or not the voice enrollment sample is a suitable submission.
    recordings.quality.
    obtained_values.SNR    		 Double N/A Read-only A float that represents the signal-to-noise ratio of the submitted voice enrollment sample in deciBels (dB).
    recordings.quality.
    obtained_values.SpeechLength    		 Double N/A Read-only A float that represents duration of the voice enrollment sample in milliseconds.
    recordings.quality.
    threshold_values.SNR    		 Double N/A Read-only A float that represents the threshold for acceptable signal-to-noise ratio of the voice enrollment sample in deciBels (dB).
    recordings.quality.
    threshold_values.SpeechLength    		 Double N/A Read-only A float that represents the threshold for acceptable duration of the voice enrollment sample in milliseconds.
    recordings.recordingId String N/A Read-only Identifier (UUID) of the voice enrollment sample.
    recordings.voiceTemplateIds String N/A Read-only Identifier (UUID) of the voice template (a construct that contains the uniquely identifying biological characteristics of a person’s voice) for this voice enrollment sample.

    data object for VOICE_VERIFICATION + IDRND

    Available with voice verification.

    Property Type Required? Mutable? Description
    matchResult.probability Double N/A Read-only A float between 0 and 1 that represents the match probability of the voice verification sample.
    matchResult.score Double N/A Read-only A float that represents a raw comparison score, intended to be used for evaluation and data calibration. A higher value means more closely matched voice verification samples.
    matchResult.voiceTemplateIds String[] N/A Read-only Array of identifiers (UUIDs) of the voice templates (a construct that contains the uniquely identifying biological characteristics of a person’s voice) for the voice enrollment samples compared.
    recordingData.antispoof.
    score    		 Double N/A Read-only A float that represents a raw comparison score, intended to be used for evaluation and data calibration. A higher value means the voice verification sample is less likely a spoofed recording.
    recordingData.antispoof.
    unsuitable_input_message    		 Boolean N/A Read-only Whether or not the voice verification sample is a suitable submission.
    recordingData.quality.
    obtained_values.SNR    		 Double N/A Read-only A float that represents the signal-to-noise ratio of the submitted voice verification sample in deciBels (dB).
    recordingData.quality.
    obtained_values.SpeechLength    		 Double N/A Read-only A float that represents duration of the voice verification sample in milliseconds.
    recordingData.quality.
    threshold_values.SNR    		 Double N/A Read-only A float that represents the threshold for acceptable signal-to-noise ratio of the voice verification sample in deciBels (dB).
    recordingData.quality.
    threshold_values.SpeechLength    		 Double N/A Read-only A float that represents the threshold for acceptable duration of the voice verification sample in milliseconds.
    recordingData.recordingId String N/A Read-only Identifier (UUID) of the voice verification sample.
    recordings.voiceTemplateIds String N/A Read-only Identifier (UUID) of the voice template (a construct that contains the uniquely identifying biological characteristics of a person’s voice) for this voice enrollment sample.

    data object for DOCUMENT_AUTHENTICATION + MITEK

    Property Type Required? Mutable? Description
    backImageDocumentId String N/A Read-only Identifier (UUID) that is referenced in mitekVerifications object to determine the image the verification ran on.
    documentEvidenceId String N/A Read-only Identifier (UUID) that is referenced in mitekVerifications object to determine the image the verification ran on.
    frontImageDocumentId String N/A Read-only Identifier (UUID) that is referenced in mitekVerifications object to determine the image the verification ran on.
    mitekVerifications Object N/A Read-only Verification results object.
    mitekVerifications.
    documentId    		 String N/A Read-only Identifier (UUID) of the image the verification ran on.
    mitekVerifications.
    judgement    		 String N/A Read-only Overall determination of the authenticity of the dossier based on the evidence presented. Permitted values are: Authentic, Fraudulent, and Undetermined.
    mitekVerifications.
    name    		 String N/A Read-only Name of the authenticator (test).
    mitekVerifications.
    notifications    		 Object N/A Read-only An object of any number of name-value pairs, where the name is a notification code and the value is its description, in the event an authenticator was unable to run.
    mitekVerifications.
    probability    		 Integer N/A Read-only A number that represents the overall authenticity score used in determining the authenticity of the dossier.
    mitekVerifications.
    verificationType    		 Integer N/A Read-only A 3-digit number (code) that indicates the type of authenticator.
    mitekVerifications.
    version    		 String N/A Read-only Version of the individual authenticator.

    data object for DOCUMENT_AUTHENTICATION + VERIFF

    Property Type Required? Mutable? Description
    veriffVerification Object N/A Read-only Verification results object.
    veriffVerification.acceptanceTime DateTime N/A Read-only Timestamp for acceptance of the document.
    veriffVerification.code String N/A Read-only Vendor's verification result code.
    veriffVerification.decisionTime DateTime N/A Read-only Timestamp of the decision on the document.
    veriffVerification.id String N/A Read-only Unique identifier (UUID) for the results.
    veriffVerification.status String N/A Read-only Vendor's status for the verification; can be approved, abandoned, declined, expired, resubmission_requested, review, started, or submitted.
    veriffVerification.vendorData String N/A Read-only Vendor's unique identifier (UUID) for the results.
    veriffVerification.reason String N/A Read-only Vendor's reason description for disapproval.
    veriffVerification.reasonCode String N/A Read-only Vendor's reason code for disapproval.

    data object for DOCUMENT_MANUAL_AUTHENTICATION + MITEK

    Property Type Required? Mutable? Description
    customerReferenceId String N/A Read-only Identifier (UUID) of the customer.
    mitekVerifications Object N/A Read-only Verification results object.
    mitekVerifications.
    authenticity.result.reasons    		 String[] N/A Read-only Array of strings with the reasons why the authenticity result is NOT_AUTHENTIC.
    mitekVerifications.
    authenticity.result    		 String N/A Read-only Whether the document authenticity is deemed AUTHENTIC or NOT_AUTHENTIC.
    mitekVerifications.
    notifications    		 Object N/A Read-only An object of any number of name-value pairs, where the name is a notification code and the value is its description, in the event an authenticator was unable to run.
    mitekVerifications.
    originality.result.reasons    		 String[] N/A Read-only Array of strings with the reasons why the originality result is NOT_ORIGINAL.
    mitekVerifications.
    originality.result    		 String N/A Read-only Whether the document originality is deemed ORIGINAL or NOT_ORIGINAL.
    mitekVerifications.
    validity.result.reasons    		 String[] N/A Read-only Array of strings with the reasons why the validity result is NOT_VALID.
    mitekVerifications.
    validity.result    		 String N/A Read-only Whether the document validity is deemed VALID or NOT_VALID.
    requestId String N/A Read-only Identifier (UUID) of the request for manual authentication.

    data object for AAMVA + MITEK

    Property Type Required? Mutable? Description
    matchResults.dateOfBirth Boolean N/A Read-only Whether the data of birth on the submitted government identity document matches the date of birth in the system of record.
    matchResults.documentNumber Boolean N/A Read-only Whether the document number on the submitted government identity document matches the document number in the system of record.
    requestId String N/A Read-only Identifier (UUID) of the request for Mitek AAMVA verification.

    Read All Verification Metadata

    Read One Verification Metadata

    Delete All Verification Metadata

    Delete One Verification Metadata

    Verification Metrics

    For each verification transaction, you can retrieve all application events for the transaction that were generated by the verification service. Use the appEvents endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions/{{transactionID}}/appEvents to retrieve application events associated with the verification transaction.

    Only those with an Identity Data Admin role are permitted to use the appEvents endpoint.

    Verification metrics object data model

    When retrieving the collection of application events for a specified transaction, the application event objects described in these data model tables are contained in an appEvents object array.

    Property Type Required? Mutable? Description
    collectionDate String N/A Read-only Date that the application event was collected
    data Object N/A Read-only Contains the application event objects where the key is the type of application event; see ADDITIONAL_INFORMATION, CAMERA, DATA_CAPTURE, DEVICE_METADATA, ERRORS, ID_CAPTURE, QR_SCANNER, or SELFIE_CAPTURE
    id String N/A Read-only Identifier (UUID) of the application event
    ADDITIONAL_INFORMATION data object
    Property Type Required? Mutable? Description
    custom_app_theme String N/A Read-only Whether or not the SDK is using a custom AppTheme; can be TRUE or FALSE
    document_submission_complete String N/A Read-only Epoch seconds of when submission completed
    sdk_initialization_type String N/A Read-only How the SDK was initialized, from a QR code (qrScanner) or a string from an already parsed QR code (qrString)
    sdk_initialization String N/A Read-only Epoch seconds of when SDK initialized
    sdk_resuming_flow String N/A Read-only Whether or not the SDK dropped a previous session and is resuming from where it left off; can be TRUE or FALSE
    CAMERA data object
    Property Type Required? Mutable? Description
    config_flash_enabled String N/A Read-only Whether or not the camera's flash is enabled; can be TRUE or FALSE
    config_focus_mode String N/A Read-only Camera focus mode; can be AUTO_FOCUS, CONTINUOUS_FOCUS, MANUAL_FOCUS
    config_resolution String N/A Read-only Resolution of the camera preview
    permission_granted String N/A Read-only Whether or not the user granted permission to use the camera; can be TRUE or FALSE
    DATA_CAPTURE data object
    Property Type Required? Mutable? Description
    number_of_otps Integer N/A Read-only Count of one time passwords (OTP) sent
    otp_canceled String N/A Read-only Whether or not the user canceled a one time password (OTP) attempt; can be email_TRUE, email_FALSE, phone_TRUE, or phone_FALSE
    otp_result String N/A Read-only Whether or not a one time password (OTP) attempt succeeded; can be email_TRUE, email_FALSE, phone_TRUE, or phone_FALSE
    otp_start String N/A Read-only Epoch seconds of when one time password (OTP) collection started
    otp_stop String N/A Read-only Epoch seconds of when one time password (OTP) collection ended
    otp_timeout String N/A Read-only Whether or not a one time password (OTP) attempt timed out; can be email_TRUE, email_FALSE, phone_TRUE, or phone_FALSE
    otp_tries Integer N/A Read-only Count of one time password (OTP) attempts
    requirements String N/A Read-only Whether or not data capture was required; can be email_TRUE, email_FALSE, phone_TRUE, or phone_FALSE
    skipped String N/A Read-only Whether or not the user skipped one time password (OTP) capture; can be email_TRUE, email_FALSE, phone_TRUE, or phone_FALSE
    start String N/A Read-only Epoch seconds of when selection of email or SMS for a one time password (OTP) started
    stop String N/A Read-only Epoch seconds of when selection of email or SMS for a one time password (OTP) ended
    DEVICE_METADATA data object
    Property Type Required? Mutable? Description
    app_package String N/A Read-only Bundle identifier or application package (URI) embedding the SDK
    browser String N/A Read-only Name of the browser; can be Chrome, Firefox, Safari, Opera, Edge, or Other
    device_manufacturer String N/A Read-only Manufacturer of the device used for the transaction, if applicable, such as Apple or Samsung
    device_model String N/A Read-only Model of the device used for the transaction, if applicable, such as iPhone14 or GalaxyS22
    device_type String N/A Read-only Type of device used for the transaction; can be IOS, ANDROID, MOBILE_WEB, or DESKTOP_WEB
    os_version String N/A Read-only Version of the operating system on the device used for the transaction, if applicable, such as 14.3 or 13
    sdk_version String N/A Read-only Version of the SDK
    user_agent String N/A Read-only User-Agent HTTP header returned by the browser
    ERRORS data object
    Capture flow errors
    Property Type Required? Mutable? Description
    camera_permission_not_granted String N/A Read-only Whether or not the user refused to grant permission to use the camera; always TRUE
    config_flash_enabled String N/A Read-only Whether or not the camera's flash is enabled; can be TRUE or FALSE
    config_focus_mode String N/A Read-only Camera focus mode; can be AUTO_FOCUS, CONTINUOUS_FOCUS, MANUAL_FOCUS
    config_resolution String N/A Read-only Resolution of the camera preview
    data_mismatch_between_front_and_back Integer N/A Read-only Count of occurrences of data mismatch between front and back
    id_capture_camera_start_error String N/A Read-only Text of any camera start errors returned by the service during identity document capture
    id_flashlight_glare Integer N/A Read-only Count of occurrences of glare from the camera flash on the identity document
    id_full_side_not_visible Integer N/A Read-only Count of occurrences where the full side of the identity document was not visible
    id_too_far Integer N/A Read-only Count of occurrences where the identity document was too far from the camera
    id_type_categorization_error String N/A Read-only Text of any type categorization errors returned by the service
    id_type_unsupported String N/A Read-only Whether or not the camera's flash is enabled; always TRUE
    selfie_camera_start_error String N/A Read-only Text of any camera start errors returned by the service during selfie capture
    selfie_face_not_aligned_x_axis Integer N/A Read-only Count of occurrences where the face was turned too far left or right
    selfie_face_not_aligned_y_axis Integer N/A Read-only Count of occurrences where the face was turned too far up or down
    selfie_face_not_aligned_z_axis Integer N/A Read-only Count of occurrences where the face was tipped too far clockwise or counterclockwise
    selfie_face_too_close Integer N/A Read-only Count of occurrences where the face was too close to the camera
    selfie_face_too_far Integer N/A Read-only Count of occurrences where the face was too far from the camera
    selfie_multiple_faces Integer N/A Read-only Count of occurrences where multiple faces were discerned in the image
    selfie_no_face_present Integer N/A Read-only Count of occurrences where no faces were discernible in the image
    Network errors
    Property Type Required? Mutable? Description
    network_lost String N/A Read-only Epoch seconds of when network was lost
    Other errors
    Property Type Required? Mutable? Description
    sdk_error String N/A Read-only Description of uncategorized errors from the SDK with the epoch seconds of when the error occurred
    app_event_error String N/A Read-only Description of errors while initializing an app event object with the epoch seconds of when the error occurred
    ID_CAPTURE data object
    Property Type Required? Mutable? Description
    barcode_captured String N/A Read-only Epoch seconds of when capture of the barcode of the identity document ended
    camera_params String N/A Read-only Camera parameters used for capture such as focus mode, resolution, and face detection service
    canceled String N/A Read-only Whether or not the user canceled identity document capture; can be TRUE or FALSE
    classification String N/A Read-only Classification of the identity document; can be Driver License or Passport
    image_#NUMBER_has_face String N/A Read-only Whether or not the image (where #NUMBER is the page number of the image) has a face; can be TRUE or FALSE
    image_#NUMBER_score Double N/A Read-only Identity document image (where #NUMBER is the page number of the image) quality score in the range of 0 to 1
    image_#NUMBER_size String N/A Read-only Resolution of the identity document image (where #NUMBER is the page number of the image)
    image_blurred String N/A Read-only Whether or not the image is blurry; can be TRUE or FALSE
    mrz_captured String N/A Read-only Epoch seconds of when capture of the machine readable zone (MRZ) of the identity document ended
    page_captured String N/A Read-only Page number and epoch seconds, separated by an underscore, for when capture of an identity document image ended. Those with front and back images have pages 1 and 2, such as 1_1650507635 and 2_1650507657. For passports, when capturing more than one page, page numbers are sequential until all pages are captured.
    skipped String N/A Read-only Whether or not the user skipped identity document capture; can be TRUE or FALSE
    start String N/A Read-only Epoch seconds of when identity document capture started
    stop String N/A Read-only Epoch seconds of when identity document capture ended
    timeout String N/A Read-only Epoch seconds of when identity document capture timed out
    total_images Integer N/A Read-only Count of captured pages of the identity document
    vendor String N/A Read-only Vendor used for capturing the identity document; can be MicroBlink, Mitek, or Ping
    QR_SCANNER data object
    Property Type Required? Mutable? Description
    canceled String N/A Read-only Whether or not QR scanning was canceled by the user; can be TRUE or FALSE
    result String N/A Read-only Result of scanning a QR code; can be VALID OR INVALID
    start String N/A Read-only Start time for scanning a QR code
    stop String N/A Read-only Stop time for scanning a QR code
    SELFIE_CAPTURE data object
    Property Type Required? Mutable? Description
    canceled String N/A Read-only Whether or not the user canceled selfie capture; can be TRUE or FALSE
    face_detection_service String N/A Read-only Service used for capturing the selfie; can be VisionKit, CoreImage, or FirebaseMLKit
    liveness_check_requested String N/A Read-only Whether or not the SDK requested a liveness check; can be TRUE or FALSE
    number_of_selfies_captured Integer N/A Read-only Count of captured selfies
    original_selfie_size String N/A Read-only Resolution of the selfie image
    selfie_face_size String N/A Read-only Percentage size of the face in the final captured selfie (includes the percent sign, %)
    selfie_pitch_angle Integer N/A Read-only Pitch angle in degrees (rotation around x-axis) where the face was turned left or right
    selfie_roll_angle Integer N/A Read-only Roll angle in degrees (rotation around y-axis) where the face was turned up or down
    selfie_score Double N/A Read-only Selfie image quality score in the range of 0 to 1
    selfie_yaw_angle Integer N/A Read-only Yaw angle in degrees (rotation around z-axis) where the face was tipped clockwise or counterclockwise
    skipped String N/A Read-only Whether or not the user skipped selfie capture; can be TRUE or FALSE
    start String N/A Read-only Epoch seconds of when selfie capture started
    stop String N/A Read-only Epoch seconds of when selfie capture ended
    timeout String N/A Read-only Epoch seconds of when identity document capture timed out
    vendor String N/A Read-only Vendor used for capturing the selfie; can be MicroBlink, Mitek, or Ping

    Read All Verify Transaction Metrics

    Read One Verify Transaction Metric

    Delete All Verify Transaction Metrics

    Delete One Verify Transaction Metric

    Verification Actions

    Reset Verification

    Users are limited in the number of verifications transactions permitted per hour and per day. If a user exceeds either limit, the cooldown period is based on the limit exceeded. If the user exceeds the limit of transactions in an hour, they must wait until an hour after the first transaction. If the user exceeds the limit of transactions in a day, they must wait until a day after the first transaction. If a user cannot wait for the end of the cooldown period, an Identity Data Admin can reset the verification limits for that user with the Reset Verification request.

    Reset Verification

    PingOne Protect

    The PingOne Protect service provides capabilities to configure and retrieve risk evaluations from internal and external risk providers based on a specified risk policy.

    Risk Policies

    A risk policy is determined by your specific configuration settings. The risk policy enables you to customize a risk evaluation to fit your use case. The policy is used during a risk evaluation to calculate the risk scores for received events. For more information about risk policies, see Risk Policies.

    Risk Evaluations

    Use risk evaluations to calculate the risk level and other risk-related details associated with a received event based on the environment's settings and data provided in the event. For more information about risk evaluation, see Risk Evaluations.

    Risk Predictors

    Risk predictors are employed by risk policies, and define thresholds for certain criteria (such as, IP Velocity, User Velocity, or User Location Anomaly) to determine whether there's the potential for fraudulent user behavior. For more information see Risk Predictors.

    Use Cases

    Risk Policies

    Risk policies enable you to customize the risk evaluations to your specific needs. Risk policies are containers for specific risk logic. You can define multiple risk policies and deploy them to initiate different authentication flow actions based on the calculated risk. By default, every PingOne environment has an associated system-level default risk policy set.

    For more information about the default risk policies, see the example response in Read Risk Policy Sets. Each risk policy set contains a list of risk policies. The maximum number of policy sets per environment is 100; the maximum number of policies per policy set is 100.

    Risk policies have the components:

    • Condition

      A Boolean predicate that defines when the policy element is evaluated to true and when it is evaluated to false.

    • Result

      Defines the final result of the risk evaluation when the condition is evaluated to true.

    Value comparison conditions

    Value comparison conditions compare a placeholder to a value. For example:

    {
  "value": "${some.placeholder}",
  "equals": "some value"
}

    The value is the outcome of one of the risk predictors.

    IP range conditions

    IP range conditions designate IP addresses for whitelisting and blacklisting.

    {
  "ipRange": ["1.1.1.1/16", "2.2.2.2/24"],
  "contains": "${transaction.ip}"
}

    Override policies

    Override policies are the ones with the highest priority. They should be listed at the beginning of the riskPolicies array. They can have value comparison condition rules or IP range condition rules. The risk policy array can have no override policies or multiple override policies.

    Combining predictors

    There are two methods of combining the predictors - Weights and Scores. When you use the Weights approach, you are determining relative weights that should be used when calculating the individual risk score for each predictor. When you use the Scores approach, you can exercise more control over the overall calculation because you can specify an exact numerical score that should be assigned when PingOne Protect determines that there is a medium or high risk level for a predictor.

    Weighted policies

    Weighted policies allow you to combine results from multiple predictors.

    Weighted policies determine risk based on aggregated weighted risk score. These policies must be listed in the riskPolicies array after all override policies are specified. An aggregated risk score involves two weighted policies, and these policies must be the last policies in the riskPolicies array.

    The weighted policies that determine the aggregated risk score complement each other and are subject to these restrictions:

    • The first weighted policy should have result.level=MEDIUM and the second should have result.level=HIGH.

    • The value for the condition.aggregatedWeights attribute for both policies must be the same.

    • The value for the condition.between.maxScore attribute for the HIGH weighted policy must be 100.

    • The value of the condition.between attribute for the two policies must be complementary. For example, if the HIGH policy has condition.between.minScore = 70, the MEDIUM policy should have condition.between.maxScore = 70.

    • condition.type should be set to AGGREGATED_WEIGHTS.

    • Choose the weight value assigned to each predictor outcome according to its significance. The following example shows the weight for two predictors: ipAddressReputation at 9 and the weight for geoVelocity at 4. The maximum and minimum scores are set at 60 and 90, respectively:

    {
  "aggregatedWeights": [
    {
      "value": "${details.aggregatedWeights.ipAddressReputation}",
      "weight": 9
    },
    {
      "value": "${details.aggregatedWeights.geoVelocity}",
      "weight": 4
    }
  ],
  "between": {
    "minScore": 60,
    "maxScore": 90
  }
}

    The value of value consists of the identifier for a specific predictor, and it takes the form ${details.aggregatedWeights.geoVelocity}, where the string after aggregatedWeights is the compact name of the relevant predictor.

    Score policies

    The JSON content below shows an example of a policy set that uses the Scores approach to risk calculation.

    Details to note about the use of score policies:

    • If you are including overrides in the policy set, they must precede the score policies.

    • The policy set must include two score policies - one that includes the score range that should be translated into MEDIUM risk, and one that includes the score range that should be translated into HIGH risk.

    • In terms of order, the MEDIUM policy must precede the HIGH policy.

    • Use condition.between.minScore and condition.between.maxScore to define the ranges for MEDIUM risk and HIGH risk. The maxScore for MEDIUM risk should always equal the minScore for HIGH risk.

    • condition.type should be set to AGGREGATED_SCORES.

    • The condition object should contain an aggregatedScores object that consists of an array of value/score pairs. The value of value consists of the identifier for a specific predictor, and it takes the form ${details.userLocationAnomaly.level}, where the string between details and level is the compact name of the relevant predictor. The value of score is the score you want to assign to that predictor when it is determined that there is a high risk for the predictor. If it is determined that there is medium risk, the predictor will automatically be assigned a score equal to half of the value you specified for high risk.

    • The array in condition.aggregatedScores must be identical in the MEDIUM policy that you define and the HIGH policy that you define.

    
{
    "id": "944fa7b4-e280-4932-80e7-01853ac9ce6d",
    "name": "aa",
    "default": false,
    "defaultResult": {
        "level": "Low"
    },
    "riskPolicies": [
        {
            "name": "ANONYMOUS_NETWORK_DETECTION",
            "result": {
                "level": "HIGH"
            },
            "condition": {
                "value": "${details.anonymousNetworkDetected}",
                "equals": true
            }
        },
        {
            "name": "GEOVELOCITY_ANOMALY",
            "result": {
                "level": "MEDIUM"
            },
            "condition": {
                "value": "${details.impossibleTravel}",
                "equals": true
            }
        },
        {
            "name": "Medium score policy",
            "result": {
                "level": "MEDIUM"
            },
            "condition": {
                "type" : "AGGREGATED_SCORES",
                "aggregatedScores": [
                    {
                        "value": "${details.userLocationAnomaly.level}",
                        "score": 40
                    },
                    {
                        "value": "${details.anonymousNetwork.level}",
                        "score": 60
                    },
                    {
                        "value": "${details.ipRisk.level}",
                        "score": 40
                    }
                ],
                "between": {
                    "minScore": 700,
                    "maxScore": 900
                }
            }
        },
        {
            "name": "High score policy",
            "result": {
                "level": "HIGH"
            },
            "condition": {
                "type" : "AGGREGATED_SCORES",
                "aggregatedScores": [
                    {
                        "value": "${details.userLocationAnomaly.level}",
                        "score": 40
                    },
                    {
                        "value": "${details.anonymousNetwork.level}",
                        "score": 60
                    },
                    {
                        "value": "${details.ipRisk.level}",
                        "score": 40
                    }
                ],
                "between": {
                    "minScore": 900,
                    "maxScore": 1000
                }
            }
        }
    ]
}

    Condition type

    The condition.type field indicates the type of policy you are defining. It can take any of the following values:

    • AGGREGATED_SCORES
    • AGGREGATED_WEIGHTS (deprecated)
    • VALUE_COMPARISON
    • IP_RANGE (for override policies or custom predictors)

    Risk staging policy set

    Risk staging policy allows you to test a policy set in parallel with another policy set. You link an existing policy set to the test policy set with a triggers object in the existing policy set, which points to the test policy set in its triggers.policySet object. Every time the existing policy set runs, it triggers the test policy set to also run. While in staging, the test policy set runs but only records its evaluation. A trigger expires 3 months from when it is set. Use Update Risk Policy Set to add the triggers object to an existing policy set.

    Base risk policy set data model

    Property Type Required? Mutable? Description
    createdAt Date Required Immutable The date and time the resource was created (format ISO-8061).
    default Boolean Optional Mutable Indicates whether this risk policy set is the environment's default risk policy set. This is used whenever an explicit policySet ID is not specified in the risk evaluation request. If this property is not specified when you create or update a risk policy, the value defaults to false, and this risk policy set is not regarded as the default risk policy set for the environment. If you set this property to true, the default property of all other risk policies in the environment is set to false.
    defaultResult Object Optional Mutable Contains the default result returned if none of the conditions in the policy are evaluated to true. At this time, the defaultResult.level value must be LOW.
    description String Optional Mutable A description for this policy set. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), numeric character, punctuation character, or space. Maximum size is 1024 characters.
    environment.id String Required Immutable The environment resource's unique identifier.
    evaluatedPredictors String array Optional Mutable The IDs for the predictors to evaluate in this policy set. In POST and PUT requests, if this property is null, all of the licensed predictors are used.
    id String Required Immutable The resource’s unique identifier.
    name String Required Mutable The name for this policy set. Valid characters consist of any Unicode letter, mark (such as, accent, umlaut), # (numeric), / (forward slash), . (period), ' (apostrophe), _ (underscore), space, or - (hyphen). Maximum size is 256 characters.
    riskPolicies String array Required Mutable The conditions associated with this policy set. See also [Risk policies data model]{#risk-policies-data-model} below.
    triggers Object[] Optional Mutable Array that contains trigger definitions for staging mode.
    triggers.type String Required Immutable Trigger type; must be POLICY_SET_STAGING.
    triggers.policySet Object Required Immutable Contains the policy set identifier to trigger.
    triggers.policySet.id String Required Immutable UUID of the policy set to trigger in staging mode.
    triggers.expiresAt String Required Immutable Date and time at which the trigger expires.
    updatedAt Date Required Immutable The date and time the resource was last updated (format ISO-8061).

    Risk policies data model

    This table lists the fields and objects that can be included in each of the elements in the riskPolicies array.

    Property Type Required? Mutable? Description
    condition Object Required Mutable Contains the condition logic that determines when a policy is evaluated to true and when it is evaluated to false.
    condition.aggregatedScores Array Required/Optional Mutable Required for score-based policies. The elements in the array are value-score pairs, representing the score that should be assigned to a specific predictor when it is determined that there is a high risk for the predictor.
    condition.aggregatedScores.value String Required Mutable Text that identifies a specific risk predictor in the environment. It uses the form ${details.xxxxxxx.level}, where the string between details and level is the compact name of the relevant predictor.
    condition.aggregatedScores.score Integer Required Mutable The score you want to assign to the predictor when it is determined that there is a high risk for the predictor. Value should be between 0 and 100. If it is determined that there is medium risk, the predictor will automatically be assigned a score equal to half of the value you specified for high risk.
    condition.type String Required Mutable Indicates the type of policy you are defining. Can be one of the following values: AGGREGATED_SCORES, AGGREGATED_WEIGHTS (deprecated), VALUE_COMPARISON, and IP_RANGE (for override policies or custom predictors).
    condition.between.minScore Integer Required/Optional Mutable Required for policies of type AGGREGATED_SCORES or AGGREGATED_WEIGHTS. The beginning of the risk score range that will be translated into the specified risk level (MEDIUM or HIGH). Must be between 0 and 1000.
    condition.between.maxScore Integer Required/Optional Mutable Required for policies of type AGGREGATED_SCORES or AGGREGATED_WEIGHTS. The end of the risk score range that will be translated into the specified risk level (MEDIUM or HIGH). Must be between 0 and 1000.
    createdAt Date Required Immutable The date and time the resource was first created (format ISO-8061).
    description String Optional Mutable A description for this risk policy. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), # (numeric), / (forward slash), . (period), ' (apostrophe), _ (underscore), space, or - (hyphen). Maximum size is 1024 characters.
    environment.id String Required Immutable The environment resource's unique identifier.
    id String Required Immutable The resource’s unique identifier.
    name String Required Mutable A name for the risk policy. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), # (numeric), / (forward slash), . (period), ' (apostrophe), _ (underscore), space, or - (hyphen). Maximum size is 256 characters.
    priority Integer Required Mutable The index of the element in the riskPolicies array.
    result.level String Required Mutable Contains the result returned if the condition is evaluated as true. If several policies are evaluated as true, the result related to the lowest priority condition is returned. For more information, see the Result attribute data model in Risk Evaluations.
    updatedAt Date Required Immutable The date and time the resource was last updated (format ISO-8061).

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    risk_admin POLICY_SET.CREATED
    risk_admin POLICY_SET.UPDATED
    risk_admin POLICY_SET.DELETED

    Create Risk Policy Set

    Read Risk Policy Sets

    Read One Risk Policy Set

    Update Risk Policy Set

    Delete Risk Policy Set

    Risk Evaluations

    The risk service provides operations to retrieve risk evaluations from internal and external risk providers based on a specified risk policy. The risk policy is determined by the customer's specific configuration settings as well as intelligence gathered from common use cases, which are then used in event evaluation to calculate risk scores for received events.

    Risk evaluation data model

    Property Type Required? Mutable? Description
    createdAt Date N/A Read-only The time the resource was created (format ISO-8061).
    details Object Optional Mutable Contains additional information about the risk evaluation. See the following [Details data model]{#details-data-model} table.
    environment.id String Required Immutable The environment resource's unique identifier.
    event Object Required Mutable Contains the attributes identifying the event. For more information about event attributes, see the following [Event data model]{#event-data-model} table.
    id String N/A Read-only The risk evaluation’s unique identifier.
    riskPolicySet.id String Optional Mutable The risk policy set's unique identifier. If this property and riskPolicySet.name are both specified, the policy set referenced by this property is used. If neither this property nor riskPolicySet.name are specified, the environment's default risk policy set is used.
    riskPolicySet.name String Optional Mutable The risk policy set associated with this name. If this property and riskPolicySet.id are both specified, the policy set referenced by riskPolicySet.id is used. If neither this property nor riskPolicySet.id are specified, the environment's default risk policy set is used.
    result Object N/A Read-only Contains the risk policy that evaluates as true. If there are several risk policies that evaluate as true, the highest priority risk policy is returned. If no risk policy evaluates as true, the defaultResult of the policy set is returned.
    result.level String N/A Read-only The risk evaluation result level. Options are HIGH, MEDIUM, and LOW.
    result.recommendedAction String N/A Read-only The recommended course of action based on the evaluation. Currently used only for policies that include a bot detection predictor, an Adversary-in-the-Middle (AitM) predictor, an email reputation predictor, or a traffic anomaly predictor. If recommendedAction is included in the response, the possible values are:
    • BOT_MITIGATION, meaning that you should take steps to handle a scenario where a bot is involved.
    • AITM_MITIGATION, meaning that you should take steps to mitigate the damage from an AitM attack. For an AitM attack, the user's credentials have been intercepted, so in addition to blocking the access request, you should lock the user's account until the password is changed.
    • TEMP_EMAIL_MITIGATION, meaning that the user has specified a disposable email address, so you should probably block the registration attempt.
    • DENY - returned when a risk level of HIGH is calculated for a traffic anomaly predictor. The recommendation is that you deny access because the suspicious activity is likely due to malicious behavior.
    result.type String N/A Read-only The risk evaluation result type. Options are VALUE, indicating any custom attribute that's defined.
    updatedAt Date N/A Read-only The time the resource was last updated (format ISO-8061).

    Event data model

    A POST request uses these properties to specify information about events processed for risk evaluation.

    Property Type Required? Mutable? Description
    browser.cookie String Optional Mutable To improve risk analysis, provide the value of a persistent cookie.
    browser.userAgent String Optional Mutable The user agent string for the browser.
    completionStatus String Optional Mutable The state of the transaction. Options are FAILED, IN_PROGRESS, and SUCCESS. If a value is not provided, the value defaults to IN_PROGRESS. The value of this property can be changed only if its current state is IN_PROGRESS.
    device Object Optional Mutable Contains information about the device being used.
    device.externalId String Optional Mutable If you want to maintain your own device IDs, you can send the device ID to the risk evaluation by using device.externalId, and this is the ID that will be used rather than the device ID provided by the Signals SDK. One situation where you may want to use this approach is if your mobile native app incorporates a WebView. In such cases, the mobile Signals SDK and the web Signals SDK will provide different device IDs. By providing your own device ID, you'll have a consistent device ID that can be used.
    evaluatedFactors.status String Optional Mutable The state of the transaction. Options are FAILED, IN_PROGRESS, and SUCCESS.
    evaluatedFactors.type String Optional Mutable The transaction type.
    flow.type String Optional Mutable The type of flow for which the risk evaluation is being carried out. Can take any of the following values:
    • REGISTRATION - initial registration of an account
    • AUTHENTICATION - standard authentication for login or actions such as password change
    • ACCESS - verification of whether user can access the relevant application, using tools such as PingAccess
    • AUTHORIZATION - verification of whether user is authorized to perform a specific action such as a profile change, using tools such as PingOne Authorize
    • TRANSACTION - authentication carried out in the context of a purchase or other monetary transaction
    The default value is AUTHENTICATION.
    flow.subtype String Optional Mutable If you want to provide additional detail about the context of the flow, you can specify a subtype in addition to type. The values that can be used for subtype are:
    • For AUTHENTICATION - ACCOUNT_RECOVERY, ACTIVE_SESSION, KERBEROS, NEO_CREDENTIALS, PASSKEY, PASSWORDLESS, USER_CERTIFICATION, USER_PASSWORD, USERNAME_RECOVERY
    • For AUTHORIZATION - ADD_ADDRESS, ADD_MFA, ADD_PAYEE, ADD_PHONE_NUMBER, ADD_USER, CHANGE_PASSWORD, DELETE_MFA, DELETE_PAYEE, UPDATE_ADDRESS, UPDATE_PHONE_NUMBER
    ip String Required Mutable The originating IP address of the authentication flow.
    origin String Optional Mutable The calling service.
    sdk Object Optional Immutable Object used to provide the data from the Signals (Protect) SDK.
    sdk.signals.data String Optional Immutable The data collected by the Signals (Protect) SDK.
    session.id String Optional Mutable The unique session ID associated with the event.
    sharingType String Optional Mutable The device sharing type. Options are UNSPECIFIED, SHARED, and PRIVATE.
    targetResource.id String Optional Mutable The ID of the target application.
    targetResource.name String Optional Mutable The name of the target application.
    user.groups String[] Optional Mutable The names of the groups in which the user is a member.
    user.groups.name String Optional Mutable The name of the group associated with the user (maximum size: 1024 characters).
    user.id String Required/Optional Mutable The ID of the user associated with the event (maximum size: 1024 characters). Required when user.type is set to EXTERNAL. When user.type is set to PING_ONE, you must provide either user.id or user.name.
    user.name String Required/Optional Mutable The name of the user associated with the event (maximum size: 1024 characters). When user.type is set to PING_ONE, you must provide either user.id or user.name.
    user.type String Required Mutable The type of user associated with the event. The possible values are PING_ONE and EXTERNAL.

    Details data model

    A POST request returns the following attributes in the details property for the specified event.

    Property Type Required? Mutable? Description
    anonymousNetworkDetected Boolean N/A Read-only Indicates whether the current authentication originated from an anonymous network (for example, proxy or VPN).
    city String N/A Read-only The city related to the current transaction from the IP address.
    country String N/A Read-only The country related to the current transaction from the IP address.
    detected Object N/A Read-only Relevant only for Bot Detection predictors and Suspicious Device predictors. Contains the information on the rule that led to the level reported.
    detected.rule.id Integer N/A Read-only Relevant only for Bot Detection predictors and Suspicious Device predictors. ID number of the rule that led to the level reported.
    device Object N/A Read-only Contains information about the device being used.
    device.estimatedDistance Double N/A Read-only The distance between the current location of the device and the location of the device when the last risk evaluation was carried out. Distance is given in meters.
    device.externalId String N/A Read-only The externally-maintained device ID that was provided in the risk evaluation request, if such an ID was included. For more details, see the Event data model.
    device.externalLastSeen Date N/A Read-only If an externally-maintained device ID was provided in the risk evaluation request, externalLastSeen is the date and time that device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.
    device.id String N/A Read-only The device ID provided by the Signals (Protect) SDK.
    device.lastSeen Date N/A Read-only The date and time the device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.
    estimatedDistance Double N/A Read-only The distance between the user's current location and the user location when a risk evaluation was last updated with the completion status SUCCESS. Distance is given in meters.
    estimatedSpeed Integer N/A Read-only The speed the user would have had to travel at to reach their current location, based on the distance from the location when a risk evaluation for the user was last updated with the completion status SUCCESS and the time elapsed since that update event. Speed is given in kilometers per hour.
    impossibleTravel Boolean N/A Read-only Indicates whether the distance between the location of the user in their previous successful authentication and current authentication infers that the user had to travel at a speed greater than 1000 kilometers per hour. This condition is marked as fulfilled, only if:
    • Location data is available for the current and previous IP address of the user.
    • This is not the first transaction that the user has performed.
    • The user’s previous successful transaction was performed less than 24 hours ago.
    • The user moved a distance of at least 100 kilometers. Thus, even if the user moved very fast, but moved only a distance of 90 kilometers, the condition is not fulfilled.
    • The user moved at a speed greater than 1000 kilometers per hour.
    .
    ipAddressReputation.domain.asn Integer N/A Read-only The autonomous system number.
    ipAddressReputation.domain.isp String N/A Read-only The ISP that registered the domain.
    ipAddressReputation.domain.organization String N/A Read-only The organization that owns the domain.
    ipAddressReputation.domain.sld String N/A Read-only The second-level domain.
    ipAddressReputation.domain.tld String N/A Read-only The top-level domain.
    ipAddressReputation.level String N/A Read-only The risk level of the evaluated IP address. Options are LOW, MEDIUM, and HIGH. If the score is less than 55, the level is LOW; if the score is greater than 77, the level is HIGH; if the score is between 55 and 77, the level is MEDIUM. Note that these guidelines could change based on data analytics and product consideration. If the ipAddressReputation.score is unknown, NULL is returned.
    ipAddressReputation.score Integer N/A Read-only Represents the calculated score of the IP address involved in the transaction. Scores range between 0 and 100. A score of 0 indicates a non-risky IP address; a score of 100 indicates a high-risk IP address. If the IP address reputation score is not available for the specific IP address, NULL is returned.
    previousSuccessfulTransaction.anonymousNetworkDetected Boolean N/A Read-only Indicates whether an anonymous network was detected. Information is available twenty-four hours after the last successful transaction.
    previousSuccessfulTransaction.city String N/A Read-only The city of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
    previousSuccessfulTransaction.country String N/A Read-only The country of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
    previousSuccessfulTransaction.ip String N/A Read-only The IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
    previousSuccessfulTransaction.state String N/A Read-only The state of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
    previousSuccessfulTransaction.timestamp String N/A Read-only The timestamp of the transaction. Information is available twenty-four hours after the last successful transaction.
    state String N/A Read-only The state or province related to the current transaction from the IP address.
    {{predictorCompactName}}.level String N/A Read-only The risk score calculated for the predictor-related transactions associated with the accessing device, and for the current authentication attempt. Options are LOW, MEDIUM, and HIGH.
    {{predictorCompactName}}.reason String N/A Read-only The reason (or reasons) provided for the risk score classification (for example, the operating system or browser type used by the device, and country in which the accessing device is located). Each reason is classified as Unusual, to indicate how much it deviates from normal user behavior, and its effect in calculating the overall predictor risk score. Note that these messages may change in the future. If you want to take action based on a certain scenario, the action should be based on the value of detected.rule.id, which is constant.
    {{predictorCompactName}}.status String N/A Read-only Additional information about the predictor evaluation outcome. Example responses are NOT_AVAILABLE, IN_TRAINING_PERIOD, or FAILED_TO_COMPUTE.
    {{predictorCompactName}}.type String N/A Read-only The type of the predictor.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    risk RISK_EVALUATION.CREATED
    risk RISK_EVALUATION.UPDATED

    Response codes

    Code Message
    200 Successful operation.
    201 Successfully created.
    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.

    Providing feedback for risk evaluations

    Use the riskFeedback endpoint to provide feedback on the accuracy of specific risk evaluations that were carried out. The request for providing feedback takes a list of feedback items, each consisting of the risk evaluation ID, a feedback category, and a reason for including it in that category (optional). In each such request, you can include feedback for up to 100 risk evaluations.

    Risk evaluation feedback data model

    Property Type Required? Mutable? Description
    evaluationFeedbackItems Array Required Immutable The collection of feedback items.
    evaluationFeedbackItems[].feedbackCategory String Required Immutable One of the following categories of feedback: FALSE_HIGH_RISK, FRIENDLY_BOT, NEW_ACCOUNT_FRAUD, COMPROMISED_ACCOUNT, AUTOMATED_ATTACK.
    evaluationFeedbackItems[].reason String Optional Immutable The reason that the specific feedback category was specified. The possible values depend upon the category chosen.
    • False high risk: OFFICE_NETWORK, COMPANY_VPN, WRONG_LOCATION, ORG_NETWORK, SUCCESSFUL_MFA, OTHER
    • Friendly bot: KNOWN_CRAWLER, KNOWN_AGGREGATOR, INTERNAL_AUTOMATION, OTHER
    • New account fraud: SUSPICIOUS_EMAIL_ADDRESS, USERNAME_GUESSING, OTHER
    • Compromised account: USER_CLAIMS_IT_IS_NOT_THEM, UNSUCCESSFUL_MFA, OTHER
    • Automated attack: CREDENTIAL_STUFFING, PASSWORD_SPRAY, OTHER
    evaluationFeedbackItems[].riskEvaluation.createdAt Date Optional Immutable The date and time the risk evaluation was carried out. Use ISO-8061 format, for example, 2024-05-01T13:44:33.417Z. This parameter is optional, but providing a value for it makes the feedback process more efficient.
    evaluationFeedbackItems[].riskEvaluation.id String Required Immutable The ID of the risk evaluation.

    Below is the sample body for a request that provides feedback on three risk evaluations. Full sample request can be found here.

    {
  "evaluationFeedbackItems":[
    {
      "riskEvaluation": { 
            "id": "15f1d245-33b3-4dba-849d-4df4b64b2d42"
       },
      "feedbackCategory": "FRIENDLY_BOT",
      "reason": "INTERNAL_AUTOMATION"
    },
    {
      "riskEvaluation": { 
            "id": "d1b638b4-638e-4c56-8fc6-872691c1bab1"
       },
      "feedbackCategory": "FALSE_HIGH_RISK",
      "reason": "COMPANY_VPN"
    },
    {
      "riskEvaluation": { 
            "id": "35f1d245-33b3-4dba-849d-4df4b64b2d45"
       },
      "feedbackCategory": "FALSE_HIGH_RISK"
    }  
   ]
}

    Create Risk Evaluation

    Create Risk Evaluation (includes device trust predictor)

    Create Risk Evaluation (with custom input)

    Read One Risk Evaluation

    Send Risk Evaluation Feedback

    Update Risk Evaluation

    Risk Predictors

    PingOne supports multiple risk predictors, which are intended to identify possible fraudulent user behaviors based on these criteria:

    • Anonymous network detection

      Malicious actors typically use anonymous networks, such as unknown VPNs, Tor, and proxies to mask their IP address. PingOne Protect analyzes IP address data from a user’s device to determine if the address is originating from any type of anonymous network. If so, the user can be prompted for step-up authentication or denied access. PingOne Protect also supports creating a whitelist of networks, ensuring that legitimate VPN users can access authorized resources.

    • IP velocity

      IP Velocity tracks the number of distinct IPs used per user. The threshold of the number of IPs per user is based on a statistical learning of the organization's past behavior. The risk predictor learns the mean average number of distinct IPs per user per unit of time (hour), and the standard deviation. The Risk Predictor then calculates the low, medium, and high thresholds of the number of IPs per user for the organization.

    • IP reputation

      IP addresses that have been involved in malicious activities, such as distributed denial-of-service (DDoS) attacks or spam activity, are considered risky. The more frequently they are used for malicious activities, the higher their risk score. If a user attempts to access an application that is associated with an IP address previously involved with suspicious activity, the probability of potentially risky behavior increases. PingOne Protect analyzes data from different intelligence sources to determine the probability an IP address is associated with malicious activity and to request stronger authentication to verify the user's identity. It also supports creating a whitelist of networks, ensuring that legitimate VPN users can access authorized resources.

    • User velocity

      User Velocity tracks the number of distinct users per IP. The threshold of the number of users per IP is based on a statistical learning of the organization's past behavior. The risk predictor learns the mean average number of distinct users per IP per unit of time (hour), and the standard deviation. The Risk Predictor then calculates the low, medium, and high thresholds of the number of users per IP for the organization.

    • User-based risk behavior

      The user-based risk behavior predictor compares a transaction with the typical behavior of the specific user. For example, if a user accesses an application that they rarely use, user-based risk behavior detects an anomaly. User-based risk behavior is a machine-learning model that continuously updates. The machine-learning model characterizes abnormal activity as low, medium, or high risk.

    • Geovelocity anomaly

      Users frequently sign on to the same application from multiple locations throughout the day. However, a time lapse between the current sign-on location and the previous location that is shorter than the time it would take to travel between the two points could indicate potentially suspicious activity. PingOne Protect analyzes location data to calculate if travel time between two session locations is physically possible. If the elapsed time is calculated to be impossible, the user can be prompted with step-up authentication or denied access. It also supports creating a whitelist of networks, ensuring that legitimate VPN users can access authorized resources.

    • User location anomaly

      User Location Anomaly detects a user's login location and checks it against previously saved authentication locations. If an authentication attempt occurs at a location whose distance from the user's expected location is greater than the radius you defined, it is considered medium or high risk, depending on the extent of the deviation from the defined radius.

    • Bot detection

      Analyzes multiple device and user behavior factors to detect non-human behavior, automated frameworks, and recorders during attempts to register or authenticate. This type of predictor requires use of the Signals (Protect) SDK.

    • New device

      New device predictors allow your risk policy to take into account the risk associated with users trying to access applications from unknown devices or devices that have not been used for sign-on in the recent past.

    • Suspicious device

      Checks for suspicious settings or mismatches between browser, operating system, and hardware attributes in order to detect situations such as emulators, superuser permissions, virtual machines, mirroring applications, and devices that have been tampered with. This type of predictor requires use of the Signals (Protect) SDK.

    • Adversary-in-the-Middle (AitM)

      Adversary-in-the-Middle is a variant of Man-in-the-Middle attacks. In AitM, a malicious actor uses a reverse proxy to position themselves between a user and an online service in order to obtain user credentials and session tokens. This type of attack circumvents the protection usually provided by OTP-based multi-factor authentication, and is a common technique in phishing attempts. The predictor checks the domain name that the user is trying to access in order to identify AitM attacks. The AitM predictor requires use of the Signals (Protect) SDK.

    • Email reputation

      Detects the use of disposable email addresses during registration. You can add the predictor to your risk policies, and you can also define a specific course of action if the result.recommendedAction field in the risk evaluation response indicates the use of a disposable email address.

    • Traffic Anomaly

      Intended for detection of traffic anomalies in terms of variables such as users, devices, and sessions, the Traffic Anomaly predictor will eventually include a variety of rules, some of which you can select to enable or disable. Currently, the predictor detects situations where there are a large number of risk evaluations requested for a single user within a short period of time, and optionally can also detect situations where the number of users per device during a given period is suspicious. When this predictor returns a value of High, it is recommended that you deny access because the suspicious activity is likely due to malicious behavior.

    • PingID Device Trust

      The PingID Device Trust predictor checks if a device is trusted by validating the trust created during the installation of the PingID Device Trust agent. Requires use of the Signals (Protect) SDK and that the agent be installed on user computers.

    • Custom risk predictors

      You can create custom predictors to assign high, medium, or low risk level based on external data that you provide or data that is accessible via the PingOne API but not included in the out-of-the-box predictor types.

    In addition to the standard risk predictors, each of which represents a single risk factor, you can create composite risk predictors for situations where you are interested in combining a number of risk factors into a single predictor. For example, a situation where you are concerned about the use of an anonymous network only in cases where a user location anomaly is also reported.

    Risk predictor evaluations

    The evaluatedPredictors property in the policy set identifies the list of predictors (by ID) to be evaluated. If there is not enough data to assess a predictor level, the evaluation result does not assign any level to the predictor. In these cases, the response returns a Not enough information to assess risk score message.

    When a predictor is added to a policy, regardless of the predictor weight, the predictor is evaluated when the policy is evaluated and its output appears in the details section of the risk service response. If you set the risk predictor's weight to 0, this predictor is evaluated but its risk assessment is not taken into account when calculating the risk score. Conversely, if the predictor is not added to the evaluatedPredictors property, or it was removed from the policy before evaluation, then the predictor is not evaluated and its output does not appear in the details section of the response.

    Base risk predictor data model

    Property Type Required? Mutable? Description
    activationAt Date Optional Mutable For New Device predictors, you can use the activationAt parameter to specify a date on which the learning process for the predictor should be restarted. This can be used in conjunction with the fallback setting (default.result.level) to force strong authentication when moving the predictor to production. The date should be in the form yyyy-mm-dd. Note that activation date uses UTC time.
    compactName String Required Immutable A unique name for the predictor. The value must be alpha-numeric (case-sensitive), with no special characters or spaces. This name is used in the API both for policy configuration, and in the Risk Evaluation response (under details).
    createdAt Date N/A Read-only The date the risk predictor was created (format ISO-8061).
    default Object Optional Mutable Contains the default values used for a new risk predictor.
    default.result Object Optional Mutable Contains the result assigned to the predictor if the predictor could not be calculated during the risk evaluation. If this field is not provided, and the predictor could not be calculated during risk evaluation:
    • If the predictor is used in an override, the override is skipped.
    • In a weighted policy, the predictor will have a weight of 0.
    default.result.level String Optional Mutable The default result level. Options are HIGH, MEDIUM, and LOW.
    default.result.type String N/A Read-only The default result type. Options are VALUE, indicating any custom attribute that's defined.
    default.score Integer N/A Read-only The score assigned to the risk predictor in a new policy by default.
    default.weight Integer N/A Read-only The weight assigned to the risk predictor in a new policy by default.
    description String Optional Mutable The description of the risk predictor. Maximum length is 1024 characters.
    detect String Optional/Required Immutable Used only for New Device, Suspicious Device, and PingID Device Trust predictors. These predictor types all use the value DEVICE for type. The detect field is used to specify the kind of devices you are trying to detect. The possible values are NEW_DEVICE, SUSPICIOUS_DEVICE, and PINGID_TRUSTED_DEVICE.
    includeRepeatedEventsWithoutSdk Boolean Optional Mutable Relevant only for Bot Detection predictors. Set the value of includeRepeatedEventsWithoutSdk to true to expand the range of bot activity that PingOne Protect can detect.
    name String Required Mutable A unique, friendly name for the predictor. The name value is case (and space) sensitive. The API does not allow two predictors with the exact same name. However, the API does not restrict creating predictors with names such as my name and My Name. This name is displayed in the Risk Policies UI, when the admin is asked to define the overrides and weights.
    licensed Boolean N/A Read-only Indicates whether the environment has the license required for the predictor.
    shouldValidatePayloadSignature Boolean Optional Mutable Relevant only for Suspicious Device predictors. If shouldValidatePayloadSignature is set to true, then any risk policies that include this predictor will require that the Signals SDK payload be provided as a signed JWT whose signature will be verified before proceeding with risk evaluation. You instruct the Signals SDK to provide the payload as a signed JWT by using the universalDeviceIdentification flag during initialization of the SDK, or by selecting the relevant setting for the skrisk component in DaVinci flows.
    type String Required Immutable Any one of the following values: ADVERSARY_IN_THE_MIDDLE, ANONYMOUS_NETWORK, BOT, COMPOSITE, DEVICE, EMAIL_REPUTATION, GEO_VELOCITY, IP_REPUTATION, MAP, TRAFFIC_ANOMALY, USER_LOCATION_ANOMALY, USER_RISK_BEHAVIOR, VELOCITY. Note that the New Device, Suspicious Device, and PingID Device Trust predictors all use the type DEVICE. To differentiate between them, you use the detect field. For COMPOSITE, see also the Composite risk predictor data model below. For MAP, see also Custom risk predictors below. For VELOCITY, see also Velocity risk predictor data model below. For TRAFFIC_ANOMALY, see also Traffic anomaly risk predictor data model below.
    updatedAt Date N/A Read-only The date the risk predictor set was updated (format ISO-8061).
    whiteList List[] Optional Mutable For the geoVelocity, ipReputation, and anonymousNetwork predictors, use whiteList to specify IP addresses (CDIRs) that should be ignored by the predictor (usually because these are IPs you know are legitimate). The list can include IPs in IPv4 format and IPs in IPv6 format. For the ADVERSARY_IN_THE_MIDDLE predictor, use whiteList to specify the legitimate domains that your users will access for your restricted resources.

    Composite risk predictor data model

    Property Type Required? Mutable? Description
    compositions Array Required Mutable Contains the objects that specify the conditions to test and the risk level that should be assigned if the conditions are met. The array can contain a maximum of three elements.
    compositions[].condition Object Required Mutable Specifies the set of conditions that are to be tested.
    compositions[].level String Required Mutable The risk level that should be assigned if the specified conditions are met. Can be HIGH, MEDIUM, or LOW.

    Traffic anomaly risk predictor data model

    Property Type Required? Mutable? Description
    rules Array Required Mutable Collection of rules to use for this traffic anomaly predictor.
    rules[].enabled Boolean Required Mutable Set to true to use the defined rule in the predictor.
    rules[].interval Object Required Mutable Object that contains the fields used to define the timeframe to consider. The timeframe can be between 1 hour and 14 days.
    rules[].interval.unit String Required Mutable The time unit for defining the timeframe for tracking number of users on the device - can be DAY or HOUR
    rules[].interval.quantity Integer Required Mutable The number of days or hours for the timeframe for tracking number of users on the device.
    rules[].threshold Object Required Mutable Object that contains the fields used to define the risk thresholds.
    rules[].threshold.medium Integer Required Mutable Number of users during the defined timeframe that will be considered Medium risk.
    rules[].threshold.high Integer Required Mutable Number of users during the defined timeframe that will be considered High risk.
    rules[].type String Required Mutable The type of rule. Currently the only valid value is UNIQUE_USERS_PER_DEVICE - for tracking the number of unique users for a device over a defined timeframe.

    Velocity risk predictor data model

    Property Type Required? Mutable? Description
    by List Optional Mutable An ordered list of JSON parameters for the values to aggregate. For example, ${event.ip},${event.user.id}.
    of String Optional Mutable A JSON pointer for the value to aggregate. For example ${event.ip} or ${event.user.id}.
    threshold Object Optional Mutable Contains information about the calculated threshold used.
    threshold.high Integer Optional Mutable The value calculated for the high threshold. If the IP was accessed by more than the high number of users during the past hour, the IP is flagged as a HIGH userVelocityByIp.level.
    threshold.medium Integer Optional Mutable The value calculated for the medium threshold. If the IP was accessed by more than the medium number of users during the past hour, the IP is flagged as a MEDIUM userVelocityByIp.level
    threshold.source String Optional Mutable The source used to calculate the threshold. This can be:
    • MIN_NOT_REACHED. If the measure is less than every.minSample, the threshold isn't calculated. Instead, a value of LOW is automatically assigned.

    • CALCULATED. Indicates the threshold was calculated.

    • ENVIRONMENT_FALLBACK. Indicates a global threshold calculated for the entire environment is used. The global threshold is used when the userVelocityByIp.threshold couldn't be calculated for the user, generally due to a lack of past transactions for the risk predictor to use for the threshold calculation.

    • DEFAULT_FALLBACK. Indicates the default threshold defined for the predictor (in threshold.medium or threshold.high) is used. The default threshold is used when ENVIRONMENT_FALLBACK (the global threshold) could not be calculated, generally due to a lack of past transactions for the risk predictor to use for the global threshold calculation.
    threshold.calculatedAt Date Optional Mutable The timestamp for the calculated threshold.
    threshold.expiresAt Date Optional Mutable Indicates when the threshold will be recalculated. The recalculation will happen before this time.
    velocity.distinctCount Integer Required Mutable The distinct count during a specified number of seconds. The duration is set using the velocity.during property. Applicable only for IP velocity predictors that have measure=DISTINCT_COUNT set.
    velocity.during Integer Required Mutable The number of seconds for the DISTINCT_COUNT duration. Applicable only for IP velocity predictors that have measure=DISTINCT_COUNT set.

    Audit reporting events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Service Event
    risk RISK_PREDICTOR.CREATED
    risk RISK_PREDICTOR.UPDATED
    risk RISK_PREDICTOR.DELETED

    Custom risk predictors

    You can define three types of custom risk predictors:

    • IP Range - for custom handling of IP-related risks
    • String Matching - definition of risk levels associated with different values of custom input provided as a string
    • Numeric Range - definition of risk levels associated with different values of custom input provided as a number

    While different fields are used for defining these three types of conditions, the basic JSON structure for the body of the request is similar for all types:

    • The top-level field type must be set to MAP.
    • The conditions are contained inside objects called map.high, map.medium, and map.low. You do not have to include all three levels, you just have to include at least one of these objects. If you include more than one level, for example, map.high and map.medium, each must refer to the same variable, for example, ${details.country}.
    • The contains field in the condition can use any of the following as the variable whose value is being checked:
      • Any field in the details object (see Risk Evaluations)
      • Any field in the event object (see Risk Evaluations)
      • Any custom attribute added to the event object simply by adding the attribute to the event object in the body of a risk evaluation request

    IP Range custom predictor - sample request body

    {
  "name": "Device IP - custom",
  "compactName": "deviceIpCustom",
  "map": {
    "high": {
        "ipRange": [
            "1.1.1.1/5",
            "2.2.2.2/8"
        ],
    "contains": "${event.ip}"
    }
  },
  "type": "MAP",
  "default": {
    "result": {
      "level": "MEDIUM"
    }
  }
}

    String Matching custom predictor - sample request body

    {
  "name": "Device country - custom",
  "compactName": "deviceCountryCustom",
  "map": {
    "high": {
        "list": [
            "Iran",
            "Syria"
        ],
    "contains": "${details.country}"
    },
    "medium": {
        "list": [
            "Ethiopia",
            "Russia"
        ],
    "contains": "${details.country}"
    }
  },
  "type": "MAP",
  "default": {
    "result": {
      "level": "MEDIUM"
    }
  }
}

    Numeric Range custom predictor - sample request body

    {
  "name": "Device Network Location",
  "compactName": "deviceNetworkLocation",
  "map": {
    "high": {
      "between": {
        "minScore": 804672,
        "maxScore": 12742000
      },
      "contains": "${details.device.estimatedDistance}"
    },
    "medium": {
      "between": {
        "minScore": 321869,
        "maxScore": 804672
      },
      "contains": "${details.device.estimatedDistance}"
    },
    "low": {
      "between": {
        "minScore": 0,
        "maxScore": 321869
      },
      "contains": "${details.device.estimatedDistance}"
    }
  },
  "type": "MAP",
  "default": {
    "result": {
      "level": "LOW"
    }
  }
}

    Composite risk predictors

    The JSON content below shows the body of a request for creating a composite predictor.

    Details to note about the content of the request body:

    • type must be set to COMPOSITE.

    • Each of the objects in the compositions array contain a condition object, which is use to specify the set of conditions to test, and the level field, which specifies the risk level that should be assigned if the conditions are met.

    • The compositions array can contain a maximum of three elements.

    • The specific predictor comparisons to carry out should use the ${details.*.level} format to specify the predictor to use. The string between details and level should be the compact name of the predictor.

    • In addition to standard and custom predictors, you can include the following risk factors in composite predictors: country (${details.country}), state (${details.state}), IP range (${event.ip}), IP domain organization (${details.ipAddressReputation.domain.organization}), ISP (${details.ipAddressReputation.domain.isp}), target resource (${event.targetResource.name}), user ID (${event.user.id}), and user name (${event.user.name}). When creating conditions with these risk factors, you can use the following comparisons:

      • equals
      • notEquals
      • contains - to check if a value is in a defined list or in an IP range
      • notContains - to check if a value is not included in a defined list or in an IP range
      • startsWith - to check if a value begins with the specified string. Can be used with ISP, IP domain organization, user ID, and user name.
      • endsWith - to check if a value ends with the specified string. Can be used with ISP, IP domain organization, user ID, and user name.
      • containsIgnoreCase - to check if a value contains the specified substring, not case-sensitive. Can only be used for user ID and user name.

    • In your composite predictors you can also include conditions that check what user groups the user belongs to. For user groups conditions, the comparisons to use are contains and notContains.

    • Use ${details.counters.predictorLevels.high}, ${details.counters.predictorLevels.medium}, and ${details.counters.predictorLevels.low} to specify criteria relating to the number of predictors in a policy that yield a high, medium, or low risk result. For criteria of this type, use the relational terms equals, greater, lower, greaterEquals, lowerEquals.

    • Within condition objects, use or for the array of conditions if it is enough for any of the conditions to be true, and and if all the criteria must be true. If none of the criteria can be true, construct an or array, then enclose it in a not object.

      Example of or:

    "compositions": [
  {
    "condition": {
      "or": [
        {
          "equals": 3,
          "value": "${details.counters.predictorLevels.high}",
          "type": "VALUE_COMPARISON"
        },
        {
          "equals": "HIGH",
          "value": "${details.anonymousNetwork.level}",
          "type": "VALUE_COMPARISON"
        },
        {
          "type": "STRING_LIST",
          "list": [
            "Italy",
            "Germany"
          ],
          "notContains": "${details.country}"
        }
      ]
    },
    "level": "HIGH"
  }
]

    Example of not:

    "compositions": [
  {
    "condition": {
      "not": {
        "or": [
          {
            "value": "${details.counters.predictorLevels.high}",
            "equals": 3,
            "type": "VALUE_COMPARISON"
          },
          {
            "value": "${details.anonymousNetwork.level}",
            "equals": "high",
            "type": "VALUE_COMPARISON"
          },
          {
            "list": [
              "ITALY",
              "GERMANY"
            ],
            "notContains": "${details.country}",
            "type": "STRING_LIST"
          }
        ]
      }
    },
    "level": "HIGH"
  }
]

    Full composite predictor example:

    {
    "name": "Composite - anonymous network and country",
    "compactName": "compositeAnonymousAndCountry",
    "licensed": true,
    "compositions": [
        {
            "condition": {
                "or": [
                    {
                        "equals": 3,
                        "value": "${details.counters.predictorLevels.high}",
                        "type": "VALUE_COMPARISON"
                    },
                    {
                        "equals": "HIGH",
                        "value": "${details.anonymousNetwork.level}",
                        "type": "VALUE_COMPARISON"
                    },
                    {
                        "type": "STRING_LIST",
                        "list": [
                            "Italy",
                            "Germany"
                        ],
                        "notContains": "${details.country}"
                    }
                ]
            },
            "level": "HIGH"
        },
        {
            "condition": {
                "and": [
                    {
                        "equals": "HIGH",
                        "value": "${details.userLocationAnomaly.level}",
                        "type": "VALUE_COMPARISON"
                    }
                ]
            },
            "level": "MEDIUM"
        }    
    ],
    "type": "COMPOSITE",
    "default": {
        "weight": 5,
        "score": 50,
        "result": {
            "level": "LOW",
            "type": "VALUE"
        }
    }
}

    Deleting risk predictors

    Create Risk Predictor (Custom - IP range)

    Create Risk Predictor (Custom - string matching)

    Create Risk Predictor (Custom - numeric range)

    Create Risk Predictor (Composite with country)

    Create Risk Predictor (Composite with country and user group)

    Create Risk Predictor (Suspicious device)

    Create Risk Predictor (Traffic anomaly)

    Read All Risk Predictors

    Read One Risk Predictor

    Update Custom Risk Predictor

    Update AITM Predictor

    Delete Risk Predictor

    Error codes

    This topic describes common PingOne top-level and detail API error messages that you might encounter when an error occurs. An error response consists of a high-level error code that must be handled by the client and optional details containing specific information on how to resolve the fault.

    The PingOne API errors return a response payload formatted as follows:

    Property Description
    id A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client, with server-side activity included for troubleshooting purposes.
    code A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all PingOne services and is human readable (such as a defined constant rather than a number). See Top-level error messages for the possible codes here.
    message A short description of the error. This message is intended to assist with debugging and is returned in English only.
    target The item that caused the error (such as a form field ID or an attribute inside a JSON object).
    details Additional details about the error to help resolve the error.
    details.code A general fault code identifying further information. See Detail-level error messages for the possible codes here.
    details.innererror Additional details to help the client developer resolve the fault (primarily for UI validation reasons). These attributes can be used:
    • rangeMinimumValue. Errors that failed due to range violation. This attribute represents the minimum value of the range.
    • rangeMaximumValue. The maximum range or value of an attribute.
    • allowedPattern. A regex pattern describing an acceptable input pattern.
    • allowedValues. A list describing acceptable values.
    • maximumValue. The maximum value allowed for the request.
    details.message Additional information about the error.
    details.target Additional information about the item causing the error.

    A top-level error message looks like this:

    HTTP/1.1 400 BAD REQUEST
{
  "id" : "6c796712-0f16-4062-815a-e0a92f4a2143",
  "code" : "INVALID_DATA",
  "message" : "The request could not be completed. One or more validation errors were in the request.”
}

    A detail-level error message provides more information about the error. Specific codes at the detail level can be introduced by each service to reflect the actions in that service. A detail-level error message looks like this:

    HTTP/1.1 400 BAD REQUEST
{
  "id" : "6c796712-0f16-4062-815a-e0a92f4a2143",
  "code" : "INVALID_DATA",
  "message" : "The request could not be completed. One or more validation errors were in the request.",
  "details" : [
  {
    "code" : "REQUIRED_VALUE",
    "target" : "username",
    "message" : "Username is required and cannot be empty."
  },
  {
    "code" : "INVALID_VALUE",
    "target" : "employeeType",
    "message" : "Invalid value for employee type."
    "innerError" : {
      "allowedValues" : [ "EMPLOYEE", "CONTRACTOR" ]
    }
  }
}

    Top-level error messages

    The following table lists the top-level error messages, the response code, and common conditions that caused the error to occur.

    Code Response code Conditions Default message Examples
    INVALID _DATA 400 Valid request structure received.
    One or more data validation errors.
    Each validation error should be described in a details object.    		 The request could not be completed. One or more validation errors were in the request. Create or update request with an attribute with an invalid data type.
    Data failed validation rules.
    Invalid value supplied for an enum.
    INVALID_REQUEST 400, 405 Invalid request received.
    Malformed JSON, malformed HTTP request.    		 The request could not be completed. The request was malformed or invalid. The JSON structure was incorrectly formatted.
    A POST request was submitted without a required body.
    Incorrect Accept or Content-Type.
    Method not allowed on an endpoint (for example, POST to a URL that does not support POST).
    REQUEST_FAILED 400 Valid request structure received.
    Error occurred during processing of the request (not strictly validation).
    Each processing error should be described in a details object.    		 The request could not be completed. There was an issue processing the request. A password check action failed.
    NOT_FOUND 404 URL specified is not found The request could not be completed. The requested resource was not found. Accessed a resource that does not exist.
    Accessed a resource that has been hidden from the user (licensing, multi-tenancy concerns).
    ACCESS_FAILED 401, 403 Request failed due to authorization issue. The request could not be completed. You do not have access to this resource. Attempted a request with and expired, invalid or missing token.
    Attempted a request where the token did not have permissions.
    Attempted a request where the token is not licensed to request, or the license was exceeded.
    REQUEST_LIMITED 429 Request was rate limited The request could not be completed. A rate or quota limit was reached. Please try again later. Rate limiting controls denied the request.
    User is over quota for the request.
    UNEXPECTED_ERROR 500 Uncaught error occurred
    Platform outage (502, 503, 500)    		 There was an unexpected error with the service. Please try again later. Identifies an internal problem such as a database connectivity issue.

    Detail-level error messages

    The following table lists the detail-level error messages, the response code, and common conditions that may cause the error to occur.

    Code Response code Top-level match Conditions Default message Examples
    CONSTRAINT_VIOLATION 400 REQUEST_FAILED A request violated a service constraint. A request violates a constraint imposed by the service. An attempt to delete a Population having Users.
    EMPTY_VALUE 400 INVALID_DATA INVALID_DATA top level error.
    Request attempted to clear an optional value (needs to be explicitly set to null).
    Nulling or clearing a required value would result in a REQUIRED_VALUE error.    		 The value cannot be empty. Attempted to update a value to an empty string.
    INSUFFICIENT_PERMISSIONS 403 ACCESS_FAILED The actor doesn't have the sufficient permissions to make the request. You do not have permissions, or are not licensed to make this request. Either the user or the token has insufficient permissions to make the request.
    INVALID_FILTER 400 REQUEST_FAILED REQUEST_FAILED top level error.
    Request contains a filter.
    Syntax errors in that filter expression.
    Unsupported operators included in filter expression.    		 The specified filter was invalid.
    The filter attribute was invalid or does not support filtering.
    The value provided is invalid.    		 Filter attribute is not filterable.
    Filter operator was invalid or not supported.
    Filter value was invalid or of a wrong type.
    INVALID_OTP 400 INVALID_DATA INVALID_DATA top level error.
    Request contains an invalid OTP.    		 Wrong OTP was provided. An incorrect OTP was submitted at sign on.
    INVALID_PARAMETER 400 REQUEST_FAILED REQUEST_FAILED top level error.
    Request contains a known query string parameter.
    That parameter contains a value that can't be processed.    		 A query string parameter or value is not valid for this request. Invalid cursor supplied using the "cursor" parameter.
    INVALID_TOKEN 401 ACCESS_FAILED A request contained an invalid token, authorization header, or both. The authorization token is either missing, invalid, or expired. A token wasn't present in the request.
    The Authorization header was missing.
    The token presented failed a signature check.
    The token presented contained invalid claims.
    The token isn't a Java Web Token (JWT).
    INVALID_VALUE 400 INVALID_DATA INVALID_DATA top level error. One or more issues were found in the request data.
    The attribute is immutable and can not be updated.
    Invalid value for attribute.    		 Age must be a number.
    Region must be "NA", "CA", "EU", or "AP".
    Email must be in email format.
    LICENSE_EXCEEDED 403 ACCESS_FAILED A licensing enforcement limit was reached. The request exceeded your license limit. Licensed for five environments, has five existing environments, an attempts to create another environment.
    LIMIT_EXCEEDED 429 REQUEST_LIMITED A rate limit was reached. The request exceeded the allowed rate limit. Too many request too quickly.
    OUT_OF_RANGE 400 INVALID_DATA INVALID_DATA top level error.
    Value for attribute is out of a defined range.    		 The request contains an attribute value that is outside the specified range. Age must be between 1 and 150
    Password length is too short.
    QUOTA_EXCEEDED 429 REQUEST_LIMITED A user, licensing or billing quota was exceeded. The request will exceed your quota. Daily SMS/Voice limit was exceeded.
    REQUIRED_VALUE 400 INVALID_DATA INVALID_DATA top level error.
    Request is missing a required attribute.    		 The request is missing a required value. Username attribute is required to create a user.
    Region is required to create an environment.
    Attempted to update an environment and remove region.
    SIZE_LIMIT_EXCEEDED 400 INVALID_DATA INVALID_DATA top level error.
    Value for attribute is too large (either in size or length).    		 The request contains an attribute value that is too large. Given name must be less than or equal to 256 characters.
    Image size must be less than 10MB.
    UNIQUENESS_VIOLATION 400 INVALID_DATA A request violated the uniqueness rule. A resource with the specified name already exists. An attempt to create a user having the same name as an existing user.
    An attempt to create an environment having the same name as an existing environment.

    Query parameter quick reference

    SCIM protocol filtering operators help you fine-tune requests that return a large number of items. The PingOne platform supports several SCIM operators. For the list of supported SCIM filtering operators, see Filtering collections conventions).

    Note: PingOne endpoint operations may support only a subset of SCIM filtering operators. In addition, the service may allow filtering only on specific attributes. For example, the /organizations endpoint allows filtering only on the name attribute using only the sw (starts with) operator.

    This topic provides a quick reference to show the SCIM operators that apply to a given PingOne endpoint operation. It also provides information about endpoint operations that support the limit filter, the order filter, and the expand filter. For general information about page limits and collection ordering, see Paging, ordering, and filtering collections. For information about resource expansion, see the "Link expansion" section of HTTP methods conventions).

    Endpoints that support SCIM filtering expressions

    The following endpoint operations allow filtering with the indicated attributes and operators. See Filtering collections conventions for SCIM operator names and descriptions.

    Endpoint SCIM operators by attribute
    /activeIdentityCounts
    • startDate: ge
    • samplingPeriod: eq
    /activities
    • recordedat: ge, gt, le, lt
    • correlationid: eq
    • actors.client.id: eq
    • actors.user.id: eq
    • actors.user.name: eq
    • resources.id: eq
    • resources.type: eq
    • resources.population.id: eq
    • action.type: eq
    /applicationSignons
    • occurredAt: ge
    /environments
    • name: sw
    • id: eq
    • organization.id: eq
    /licenses
    • beginsAt: lt
    /populations
    • name: sw
    • id: eq
    /environment/{{envID}}/roles
    • type: eq
    /templates
    • createdAt: eq, ne, gt, ge, lt, le
    • updatedAt: eq, ne, gt, ge, lt, le
    • default: eq
      • locale: eq, sw
    • deliveryMethod: eq
    /totalIdentities
    • startDate: eq
    • endDate: eq
    /userActivities
    • startDate: eq, gt, ge, lt, le
    • endDate: eq, gt, ge, lt, le
    /users
    • enabled: eq
    • population.id: eq
    • {{customStringAttributes}}: eq, sw (see note below)
    • linkedAccounts[identityProvider.id eq "{{identityProviderID}}"]
    • linkedAccounts[externalId eq "{{externalID}}"]
    • memberOfGroups[id eq "{{memberOfGroupID}}"]
    • memberOfGroups[type eq "{{typeString}}"]
    /users/{{userID}}/devices
    • status: eq
    • type: eq

    Endpoints that support resource expansion

    The following endpoint operations support resource expansion using the expand={resource} filter.

    Endpoint Target resource
    /environments
    • expand=billOfMaterials
    /environments/{{envID}}
    • expand=billOfMaterials
    /environments/{{envID}}/apiServers/{{apiServerID}}/operations/{{apiServerOperationID}}
    • expand=groups
    • expand=scopes
    • expand=authenticationPolicies
    /environments/{{envID}}/applicationRoles/{{appRoleID}}/users
    • expand=user
    /environments/{{envID}}/dataExplorations
    • expand=entries
    /environments/{{envID}}/fido2Policies
    • expand=deviceAuthenticationPolicies
    /environments/{{envID}}/identityProviders/{{providerID}}
    • expand=attributes
    /resources
    • expand=scopes
    /resources/{{resourceID}}
    • expand=scopes
    /schemas/{{schemaID}}
    • expand=attributes
    /users
    • expand=populations
    /users/{{userID}}
    • expand=populations
    /users/{{userID}}/devices
    • expand=order
    • expand=typeDisplayNames
    /users/{{userID}}/linkedAccounts
    • expand=identityProviders
    /users/{{userID}}/linkedAccounts/{{linkedAccountID}}
    • expand=identityProvider
    /users/{{userID}}/password
    • expand=passwordPolicy

    Endpoints that support ordering by attribute

    The following endpoint operations support resource expansion using the order={attribute} filter.

    Endpoint Attribute
    /activeIdentityCounts
    • order=startDate
    /licenses
    • order=beginsAt
    /templates
    • order=updatedAt
    • order=createdAt
    /templates/{{templateName}}/contents
    • order=updatedAt
    • order=createdAt

    Endpoints that support page limits

    The following endpoint operations support page limits using the limit filter. See Paging, ordering, and filtering collections for more information.

    Paging, ordering, and filtering collections

    Pagination

    PingOne supports cursor-based pagination to return large collections in consumable pages. When an operation supports pagination, the following conventions are used:

    • Page limits

      Page limits are requested using the limit query string. If the limit parameter value is omitted, the operation returns the lesser of the service-defined maximum page size or the number of items in the collection.

    • Self, next, and previous links

      The response body includes a self link in the _links object. If there are more pages available, the response includes a next link in the _links object. If there are previous pages of results available, the response includes a prev link in the _links object.

    • Multiple pages

      If there is more than one page, the response returns a URL-safe cursor in the cursor query string parameter for the next or prev links.

    • Response metadata

      The response can include the following metadata about the results in the body of the payload:

      • count (optional).

        Describes the number of items in the collection or result set (such as the total item count). If a response does not return a count attribute, this usually means there are many in the result set.

      • size (optional).

        Describes the size of the page of results (such as the limit or service-defined maximum page size).

    Here is a sample request that limits the collection returned to a maximum of 2.

    GET {{apiPath}}/environments/{{envID}}}/populations?limit=2 HTTP/1.1

    Here is the response body.

    {
 "_links" : {
  "self" : { "href" : "https://api.pingone.com/v1/environments/{{envID}}/populations?limit=2" },
  "next" : { "href" : "https://api.pingone.com/v1/environments/{{envID}}/populations?cursor=xygdhs&limit=2" }
 },
 "count" : 50,
 "size" : 2,
 "_embedded" : {
  "populations" [
   {
    "name" : "Accounting",
    "id" : "12345-aaa-12345"
   },
   {
    "name" : "Engineering",
    "id" : "12345-aaa-12346"
   }
  ]
 }
}

    Ordering collections

    The PingOne API supports ordering collection results. The following conventions are used:

    • order query string

      The order query string parameter specifies the attribute used to order the results. To return a collection in descending order, prefix the attribute with a minus sign ("-"). Here is a sample of ordering on the name attribute in descending order:

      https://api.pingone.com/v1/environments/{{envID}}/variables?filter=name%20co%20%22r%22&order=-name

    • Multiple column ordering

      An operation can support ordering multiple columns in the order parameter by separating the columns with a comma. If an operation supports multiple columns, it treats the comma as a "THEN BY" directive. For example, order=dateTime,name indicates that the collection is sorted by dateTime then by name.

    Filtering collections

    Requests that return a large number of items can be filtered using the filter query string parameter. The PingOne platform supports the SCIM protocol filtering operators listed in the following table. However, a particular operation may not support all SCIM filtering operators. If a filtering operator is not supported, the operation returns 400 REQUEST_FAILED code in the response. The details section of the message returns an INVALID_FILTER code as the cause of the error.

    Operator Description Behavior
    eq equal The attribute and operator values are identical.
    ne not equal The attribute and operator values must not be identical for a match.
    co contains The entire operator value must be a substring of the attribute value for a match.
    sw starts with The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical.
    ew ends with The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical.
    pr present (has value) If the attribute has a non-empty or non-null value, or if it contains a non-empty node for complex attributes, there is a match.
    gt greater than If the attribute value is greater than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
    ge greater than or equal to If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
    lt less than If the attribute value is less than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
    le less than or equal to If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.

    For example, here is a sample SCIM filtering expression that returns users with a last name of "Smith" and a phone number that starts with the "512" area code:

    https://api.pingone.com/v1/environments/{{envID}}/users?filter=name.family eq "Smith" and mobilePhone sw "512"

    Here is the same filter with URL-encoding to account for spaces (%20) and quotation marks (%22):

    https://api.pingone.com/v1/environments/{{envID}}/users?filter=name.family%20eq%20%22Smith%22%20and%20mobilePhone%20sw%20%22512%22

    For more information about the SCIM Protocol Specification, see "Section 3.4.2.2. Filtering," in the SCIM Protocol Specification.

    Password encoding

    PingOne supports the following Key Derivation Functions (KDF) and crytographic ciphers as methods for password encoding:

    Method PingOne Identifier
    PBKDF2 {PBKDF2}
    ARGON2 {ARGON2}
    MSCrypto library {MSKCC_PBKDF2}
    Scrypt {SCRYPT}
    BCrypt {BCRYPT}
    SSHA N/A

    The PingOne identifier for the method must be pre-pended to the encoding generated. See the discussion of the specific method for the format.

    The common password-encoding use cases for the PingOne Platform APIs are:

    Pre-encoded passwords

    Pre-encoded passwords must use the LDAP userPassword syntax supported by PingDirectory and other directory servers. For more information about the LDAP userPassword attribute, see Hashed attribute values for userPassword. Note that in this specification, the userPassword syntax represented as userpasswordvalue = cleartext-password / prefix b64-hashandsalt should be read as:

    userpasswordvalue = cleartext-password

    or

    userpasswordvalue = prefix b64-hashandsalt

    If a pre-encoded password isn't accepted by PingOne, it doesn't conform to either of these encoding schemes.

    Generating the salt

    All of the encoding methods supported by PingOne require a salt to randomize the hashed value generated by the Hash-based Message Authentication Code (HMAC) used. Use only cryptographically strong random number generators (CSPRNG) to generate the salt. You'll generally find this in the cryptography library for your language and platform. Some of the most common are:

    Language/Platform Description
    Linux and macOS The /dev/random or /dev/urandom sources.
    Windows The BCryptGenRandom function from the Cryptography API: Next Generation (CNG) or higher level cryptography libraries.
    C# System.Security.Cryptography.RandomNumberGenerator.Create() from .NET Framework or .NET Core.
    Python Either os.urandom() or the secrets library.
    Java The java.security.SecureRandom system class.
    JavaScript Either window.crypto.getRandomValues(Uint8Array) for client side (Web browser), or crypto.randomBytes() for server-side (Node.js).

    PBKDF2

    PBKDF2 is a Key Derivation Function (KDF) described in RFC 2898. The standard format is:

    key = pbkdf2(password, salt, iterations, hash-function, derived-key-length)

    PingOne APIs require a slightly modified version of this format, where the PingOne identifier for the encoding method is pre-pended to a Base64 encoding of the parameters:

    "{PBKDF2}" + base-64-encode(`version-hex`, `salt-length-hex`, `salt`, `iterations-hex`, `encoded-password`)

    Any spaces in the hex values are ignored.

    The resulting encoding that can be passed to PingOne APIs will then look similar to this:

    {PBKDF2}ARDCg7vxrqqSDV/UzQ5N9j+XJxDv0E64J9X5aHSZk4108X3esUoaKqGJePteFKJxT6qPkQ==

    PBKDF2 parameters for PingOne

    Spaces are ignored in the hexadecimal values.

    Parameter Description
    encoded-password The user password. The password is assumed to be encoded.
    version-hex A hexadecimal encoding of the version identifier for the PKDF2 and the HMAC combination to use. The version identifier can be any one of:
    • 00 if PBKDF2WithHmacSHA1
    • 01 if PBKDF2WithHmacSHA256
    • 02 if PBKDF2WithHmacSHA384
    • 03 if PBKDF2WithHmacSHA512
    .
    salt-length-hex A hexadecimal encoding of the length of the salt. This must be between 8 and 127 characters in length.
    salt A securely-generated cryptographically strong random number.
    iterations-hex A hexadecimal encoding of the number of iterations to repeat the HMAC identified in version-hex (for example, 10,000). This can be between zero and 2,147,483,647. In general, use the maximum number of iterations that's acceptable for the performance of your application.

    Argon2

    Argon2 is a KDF described in RFC 9106. The standard format is similar to this:

    argon2.hash(password, type, iterations, memory, parallelism, hash_len, salt)

    PingOne APIs require a slightly modified version of this format:

    "{ARGON2}" + type + version, memory, iterations, parallelism

    The resulting encoding that can be passed to PingOne APIs will then look similar to this:

    $argon2i$v=19$m=64,t=2,p=8$d2pLMjlIUWk2eGU2OFZtVA$dr9M3P+yMs4qv/eFyh5WYw

    Argon2 parameters for PingOne

    Parameter Description
    password The user password to encode.
    type One of the supported Argon2 types: Argon2i, Argon2d, Argon2id.
    version Specified as v=. The current version is decimal 19. Typically, this is unspecified, and defaults to the current version.
    memory Specified as m=. The amount of memory to use in kilobytes. In general, use the maximum amount of memory that's acceptable for the performance of your application.
    iterations The number of iterations that's acceptable for the performance of your application. Typically, start with a 2 - 4 iterations, and modify this based on the desired execution time. The number of iterations must be between 1 and 2^32 − 1.
    parallelism The degree of parallelism to use is determined by the number of CPU cores on the server. Double the number of CPU cores to get the value here.
    salt A securely-generated cryptographically strong random number used to salt the specified parameters. The salt length must be between 8 and 2^32 − 1 byte.
    hash-len The desired hashed output length in bytes. Applied to the specified parameters.

    See the Argon2 Hash Generator to generate examples.

    Scrypt

    Scrypt is described in RFC 7419. Like other KDFs, Scrypt is designed to be expensive, so that attacks against Scrypt-encoded passwords are also expensive. However, Scrypt is different from other KDF algorithms because it is designed to consume a substantial amount of memory during the course of encoding a password, and to require pseudorandom access to portions of that memory. This makes the cost of generating a password dependent upon memory access latency in addition to CPU performance, and reduces the ability to parallelize password cracking attempts.

    PingOne uses the "c2NyeXB0" format, where c2NyeXB0 is the base64-encoded representation of "scrypt".

    The resulting encoded string is base64-encoded, and the unencoded value always starts with the bytes "scrypt", and is "c2NyeXB0".)

    PingOne APIs require a slightly modified version of the c2NyeXB0 format, where the PingOne identifier for the encoding method is pre-pended to the formatting identifier "c2NyeXB0":

    "{Scrypt}" + base-64-encode("scrypt", the-zero-byte, logN, r, p, salt, encoded-password)

    Encoding details

    In the aggregated parameter values "scrypt" + the-zero-byte + logN + r + p + salt:

    • The first 16 bytes is the first half of the SHA-256 encoding.

    • Apply the HMAC-SHA-256 algorithm to the first 64 bytes

    • Append the final 32 bytes to the final encoding.

    The initialization key for the HMAC-SHA-256 algorithm is the last 32 bytes of the SCRYPT algorithm output, using the specified values for encoded-password, salt, logN, r, p, and a 64 byte block size.

    The string that can be passed to PingOne APIs will then look similar to this:

    {Scrypt}c2NyeXB0/UzQ5N9j+XJxDv0E64J9X5aHSZk4108X3esUoaKqGJePteFKJxT6qPkQ==

    Scrypt parameters for PingOne

    There is a 32 byte salt parameter:

    • logN is one byte
    • r and p are both 4 bytes
    • logN, r, and p use two's complement representation
    Parameter Description
    password The user password to encode.
    logN A 1 byte value (two's complement) for the exponent to use for the CPU/memory cost factor. The cost factor must be a power of two, so the value of this property represents the power to which two is raised. The CPU/memory cost factor specifies the number of iterations required for encoding the password, and also affects the amount of memory required during processing. A higher cost factor requires more processing and more memory to generate a password, which makes attacks against the password more expensive. The value must be less than 128*r/8, where r represents the configured block size. The amount of memory that will be consumed in the course of generating the password is 128*2^N*r bytes, where N represents the CPU/memory cost factor exponent and r represents the configured block size.
    r A 4 byte value (two's complement) for the block size for the digest that will be used in the course of encoding passwords. Increasing the block size while keeping the CPU/memory cost factor constant will increase the amount of memory required to encode a password, but it also increases the ratio of sequential memory access to random memory access (sequential memory access is generally faster than random memory access). The value must be greater than or equal to one.
    p A 4 byte value (two's complement) for the number of times that Scrypt is to perform the entire encoding process to produce the final result. The amount of processing required to encode a password increases linearly with the value of this parameter. If an attacker uses an Scrypt implementation that supports the use of multiple threads to perform multiple encodings in parallel, then it also linearly increases the amount of memory required.
    salt A securely-generated cryptographically strong random number used to salt the specified parameters. The salt length is 32 bytes.

    Bcrypt

    BCrypt is a KDF based on the Blowfish cipher, and incorporates the Blowfish HMAC to hash the password. The standard format is:

    key = Bcrypt(password, cost, salt)

    PingOne APIs require a slightly modified version of this format:

    "{BCrypt}" + "$" + algorithm + "$" + cost + "$" + base-64-encode(salt) + base-64-encode-minus-one(key0)

    The resulting encoding that can be passed to PingOne APIs will then look similar to this:

    {BCrypt}$2y$10$xUtlkL33uoLU3jU7M7lkNOb0PbQQ7lKNqKuJLnZa4AzvXRWSq5Vxe

    BCrypt parameters for PingOne

    Spaces are ignored in the hexadecimal values.

    Parameter Description
    $ The prefix indicating a parameter.
    algorithm The version of BCrypt to use. Generally, this should be "$2a". However, this can be any one of the versions: 2a, 2b, 2x, 2y. The versions 2x and 2y are relevant only if you've been using crypt_blowfish, a PHP implementation of BCrypt. The version 2b is relevant only if you've been using OpenBSD.
    cost A two digit number between 4 and 31 (inclusive). If the cost is less than 10, then prepend a zero (for example, 6 -> 06). This indicates the number of iterations to repeat the HMAC. In general, use the maximum number of iterations that's acceptable for the performance of your application.
    base-64-encode(salt) A securely-generated cryptographically strong random number.
    base-64-encode-minus-one(key0) This is the base64 encoding algorithm with the final byte of the base64 encoding removed. The argument key0 is the encrypted key (for example, BCrypt(password, cost, salt)), except the last byte is replaced with "0x00".

    MSCrypto library

    Use the Microsoft method Crypto.hashPassword() to encode passwords, then import those passwords into PingOne using the {MSKCC_PBKDF2} method.

    MSCrypto uses PBKDF2 with HMAC-SHA1, 128-bit salt, 256-bit key length, and 1000 iterations.

    PingOne APIs require this format:

    "{MSKCC_PBKDF2}" + base-64-encode(0x00 + salt + digest(password, salt-128, iterations, key-length))

    Any spaces in the hex values are ignored.

    The resulting encoding that can be passed to PingOne APIs will then look similar to this:

    {MSKCC_PBKDF2}ARDCg7vxrqqSDV/UzQ5N9j+XJxDv0E64J9X5aHSZk4108X3esUoaKqGJePteFKJxT6qPkQ==

    MSCrypto parameters for PingOne

    Spaces are ignored in the hexadecimal values.

    Parameter Description
    0x00 A byte of zeros.
    salt A securely-generated cryptographically strong random number.
    digest The PBKDF2 algorithm.
    password The user password. The password is assumed to be encoded.
    salt-128 A securely-generated cryptographically strong random number of 128 bits.
    iterations A hexadecimal encoding of the number of iterations to repeat the HMAC-SHA1 (for example, 10,000). This can be between zero and 2,147,483,647. In general, use the maximum number of iterations that's acceptable for the performance of your application.
    key-length 256 bits.

    SSHA methods

    The SSHA algorithms incorporate the SHA cryptographic hash functions to hash the password. The PingOne-specific format for all of the SSHA variants is:

    "{SSHA-variant}" + base-64-encode(digest(password + salt) + salt )

    The plus sign (+) indicates concatenation.

    In addition, PingOne supports the following formats for both SHA256 and SHA1. The other variants do not support these formats.

    "{SSHA-variant}" + base-64-encode( digest(password + salt) + salt )
"{SSHA-variant}" + base-64-encode( digest(salt + password) + salt )

    SSHA parameters for PingOne

    Parameter Description
    SSHA-variant The SSHA variant to use. This can be one of the following: SSHA1, SSHA256, SSHA384, SSHA512.
    digest The password encoding using the specified SSHA variant.
    password The user password to encode.
    salt A securely-generated cryptographically strong random number.

    External transaction and session IDs

    In order to help track transactions, the PingOne platform supports the following custom HTTP headers across all endpoints:

    • X-Ping-External-Transaction-ID
    • X-Ping-External-Session-ID

    You can optionally pass these headers to PingOne products to correlate with your own transactions and sessions. If you pass these headers in a request, PingOne returns the same headers in the response.

    PingOne validates all custom HTTP headers.

    Rules

    • The maximum length of the header is 100 characters. If exceeded, the header will be truncated to 100 characters.

    • Any invalid characters will be converted to underscores. The following characters are allowed:

      • Unicode letters, combining marks, numeric characters, dots, underscores, dashes

      • /, @, =, #, +

    TLS and cipher suite requirements

    Transport Layer Security

    TLS version 1.2 is supported.

    Cipher suites

    auth.pingone.com

    TLS 1.2 (suites in server-preferred order)

    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (0xcca8) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (0xc028) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xc027) ECDH x25519 (eq. 3072 bits RSA)

    api.pingone.com

    TLS 1.2 (suites in server-preferred order)

    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (0xcca8) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (0xc028) ECDH x25519 (eq. 3072 bits RSA)

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xc027) ECDH x25519 (eq. 3072 bits RSA)

    PingOne Localization

    These PingOne services use or support language localization:

    • Agreements

      • The agreements service uses a locale property on agreement language resources to identify an enabled language in which content can be presented to end users.

      • Agreement languages must be enabled through the PingOne language management service.

    • Forms

      • The forms service uses a languageBundle property that provides a map of i18n keys to their translations.

      • Language support associated with the language bundle must be enabled through the PingOne language management service.

    • Language Management

      • An environment default language must be specified and enabled.

      • Languages that support localization of PingOne agreements, forms, and notifications content must be enabled.

    • Notifications

      • Notifications template resources use a locale property to identify an enabled language in which notification content can be presented to end users.

      • Notifications languages must be enabled through the PingOne language management service.

    • Users

      • Users resources use a locale property to localize such items as currency, date time format, or numerical representations.

      • Users resources use a preferredLanguage property to specify an end user’s preferred written or spoken language. This property can be a factor in determining the language shown to end users for agreement and notification content.

    Browser settings and localization

    The following PingOne services use the end user's browser settings as a factor to determine which language to present to users.

    • The Forms service translates i18n keys based on the end user's browser settings for preferred languages. For more information, see Localization of forms.

    • The Agreements service uses the browser's locale setting as a factor to present localized content to users. For information about the conditions needed to use the browser's settings, see Localization of agreements.

    • PingOne sign-on screens, the PingOne self-service app, and the PingOne app portal also use the end user's browser settings to determine the language to present at runtime.

    DaVinci flows and localization

    DaVinci flows use the PingOne forms service to create the sign-on screens presented to end users. These screens follow the same localization runtime logic described in the forms service. For detailed information about DaVinci flows and language support, see Localizing flows with PingOne.

    Localization of agreements

    An agreement must support the default environment language. The condition of having "agreement content to show" requires that at least the environment's default language is configured as an agreement language resource. The agreement language resource that supports the environment's default language must be enabled. The agreement language resource can have its enabled property set to true only if there is "localized content to show" configured on its associated agreement revisions resource.

    Agreement language resources define the locale property, which applies to all agreement revision resources associated with the language.

    Agreement language resources

    The locale property on the agreement language resource specifies a tag for identifying the language resource associated with an agreement consent (for example, en-US).

    How localized agreement content is presented to users

    Agreement languages are defined by either the language code (for example, en) or the combination of language code and country code (for example, en-GB). For identifying languages, the API follows the tags for identifying languages described in RFC_4646. For selecting a language code to use in an agreement, the API follows the matching of language tags described in RFC_4647.

    When an agreement is active, languages are presented to the user in the following order:

    1. User preference: The end user receives agreement content in the language that matches the user's preferredLanguage property value.

    2. Browser preference: If the user's preferredLanguage is not configured (or enabled) as one of the supported agreement language resources for this agreement, the end user receives agreement content in the language associated with the browser's configured locale.

    3. Environment default language: If the browser's configured language is not one of the enabled agreement language resources for the agreement, then the agreement content is presented to the end user in the environment's default language.

    For more information, see Agreement Management.

    Localization of forms

    You can add translatable keys for any user-facing text in your forms, including the input field labels, button labels, and rich text. After adding these keys, the text can be translated based on the end user's browser settings for preferred languages.

    The form resource includes a languageBundle property that provides a map of i18n keys to their translations. This object includes both the keys and their default translations. The PingOne language management service finds this object and creates the new keys for translation for this form.

    After you have added translatable keys, you must configure which languages are enabled for translation (see Language Management).

    For more information, see Forms.

    Localization and language management

    Language resources are used by other user-interactive features in the platform (such as agreements, notifications, and forms) to present information in a designated language for a specified user.

    To present localized content to end users, that language, or a group of languages, must be enabled. In PingOne, the Language Management service supports a maximum of 14 language translation catalogs, and it provides translated string catalogs for the following languages out of the box:

    Code Language
    de German
    en English
    es Spanish
    fr French
    fr-CA French (Canadian)
    it Italian
    ja Japanese
    ko Korean
    nl Dutch
    pt Portuguese
    ru Russian
    th Thai
    tr Turkish
    zh Chinese

    Within the language service, the /translations/{{languageCode}} endpoint provides operations to view the custom string translations for a specified language and update localized strings for specified user interface elements.

    For more information, see Language Management.

    Localization of notifications

    Each environment has a set of predefined notifications templates it can access. A template represents a specific process flow, for example, device_pairing or strong_authentication, that requires a notification. Each template defines the deliveryMethods (Email, SMS, Voice or Push) that it supports. A content defines one message text choice for a notification. Each content is always associated with one template and has one deliveryMethod and one locale.

    Runtime logic for content selection

    Each content, whether default or custom, is associated with one template, one deliveryMethod, one locale, and optionally, one variant (For more information on variants, see Creating custom contents). When a request for content is executed at runtime, it includes a template, deliveryMethod, locale and, optionally, a variant.

    1. PingOne matches the best text notification content for the user based on locale and variant name.

    2. If a locale is specified on the request (for example, on the notification.template.locale property on POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices), it overrides the user's preferred language setting.

    3. If the locale on the request (or the user's preferred locale) does not match a notification content with the exact locale, PingOne uses the best matching locale (based on the language, ignoring the region) if available. For example, es-ES falls back to es.

    4. For the locale property value, PingOne supports language tags with quality values as described in Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content.

    5. For voice notifications, PingOne uses the best matching language based on the supported languages of the provider (Twilio, Syniverse, or a custom provider).

    For more information, see Notifications.

    Localization and user properties

    The following properties can be set on the user resource to select the language presented to end users for some PingOne interface elements.

    • locale

      This is the user’s default location. This property may be explicitly set to null when updating a user to unset it. It is used for localizing such items as currency, date time format, or numerical representations. If provided, it must be a valid language tag as defined in RFC 5646.

    • preferredLanguage

      The user’s preferred written or spoken languages. This may be explicitly set to null when updating a user to unset it. If provided, the format of the value must be a valid language range and the same as the HTTP Accept-Language header field (not including Accept-Language:) and is specified in Section 5.3.5 of RFC 7231. For example: en-US, en-gb;q=0.8, en;q=0.7.

    For more information, see Users.

    Load Testing

    Load testing is a regular part of managing your systems and their connections to the PingOne platform, especially to test anticipated increases or surges in usage or traffic. The following guidelines will help you conduct load testing in a way that will yield accurate results based on your service level agreement (SLA) and the inherent limits of the PingOne platform. For more information, see Platform Limits.

    The first step in any load testing process is to create a Support Case notifying Ping Identity of the planned testing before you begin.

    Ping Identity monitors customer traffic to proactively detect attacks and other threats. Load testing can be difficult to distinguish from attacks and other malicious actions. Unannounced load testing can trigger the following:

    • Ping Identity's threat detection systems might automatically block some or all traffic from your organization. This can not only invalidate the results of your load testing, but also disrupt your production environment user experience.

    • Surges in SMS and email traffic can result in service providers restricting or shutting down all traffic from the source domains associated with those surges.

    • Both of these can degrade the reputation scores of the sending domains and IP addresses, causing Ping Identity's threat detection systems to delay, restrict, or block traffic from those sources.

    These effects can negatively impact your real end users ability to register with an email confirmation, to sign on to your PingOne environment, or to authenticate using SMS passcodes. These effects can persist for a long time after your load test, and are not quickly or easily fixed once they occur.

    Creating a Support Case well in advance of any load testing allows Ping Identity to adjust threat detection systems in advance of anticipated traffic surges. This will yield more accurate results for your load testing with minimal disruptions to your regular operations.

    Load testing guidance

    When you notify Ping Identity ahead of your load testing we can provide guidance on response times and load limits specific to your SLA, so you can know what to expect in terms of platform performance. The information we provide includes:

    • Whether it is appropriate to increase your capacity allotment beyond your current SLA.
    • Transactions per second (TPS) and response time expectations, including rate limit variations per endpoint.

    If your expected surge exceeds these limits, you can coordinate with Ping Identity to meet your needs.

    Roles and Permissions in PingOne

    The ability to perform an action in PingOne is determined by Role-Based Access Control (RBAC). For example, when you initiate a request to a PingOne endpoint, you must have the role required by the endpoint to execute the request. Roles define the permissions available to users with that role.

    See PingOne Role Permissions for the PingOne roles and their permissions.

    See PingFederate SSO admin permissions for the available PingFederate roles.

    See PingOne Permissions by Identifier for all permissions.

    You'll notice that our endpoint documentation uses icons to indicate the role or roles needed to access the endpoint (see Read All Built-in Admin Roles for an example).

    The PingOne roles are:

    Role Icon Abbr. Can Assign
    Organization Admin Organization Admin role ORG Environment Admin
    Environment Admin Environment Admin role ENV All roles except Organization Admin
    Identity Data Admin Identity Data Admin role IDA Identity Data Admin, Identity Data Read-Only Admin
    DaVinci Admin DaVinci Admin role DVA DaVinci Admin, DaVinci Read-Only Admin
    Custom Role Admin Custom Role Admin role ROLE None
    Application Owner Application Owner role APP-O None
    Identity Data Read-Only Admin Identity Data Read Only role IDA-R None
    Configuration Read-Only Admin Configuration Read Only role CFA-R None
    DaVinci Read-Only Admin DaVinci Admin Read Only role DVA-R None
    Client Application Developer Client Application Developer role APP None

    PingFederate SSO Admin Permissions

    Admins can SSO from PingOne into PingFederate with the following roles:

    PingFederate System Admin

    PingFederate System admins have the following permissions:

    • Configure partner connections and most system settings, except the management of local accounts and the handling of local keys and certificates.
    • Access to PingOne administrator console.
    PingFederate Auditor

    PingFederate Auditors have the following permissions:

    • View-only permissions for all administrative functions.
    • Access to PingOne administrator console.
    PingFederate Crypto Admin

    PingFederate Crypto admins have the following permissions:

    • Manage local keys and certificates.
    • Access to PingOne administrator console.
    PingFederate Expression Admin

    PingFederate Expression admins have the following permissions:

    • Configure partner connections and most system settings, except the management of local accounts and the handling of local keys and certificates.
    • Map user attributes by using the expression language, Object-Graph Navigation Language (OGNL).
    • Access to PingOne administrator console.
    PingFederate User Admin

    PingFederate User admins have the following permissions:

    • Create users, deactivate users, change or reset passwords, and install replacement license keys.
    • View-only permissions for all administrative functions.
    • Access to PingOne administrator console.

    PingOne Role Permissions

    A permission in a row aggregates actions that can be applied to a resource within a category and lists the roles that have that permission.

    Category Permission ORG ENV IDA DVA APP‑O IDA‑R CFA‑R DVA‑R ROLE APP
    Applications Create, read, update, and delete application ENV APP
    Create, read, update, and delete attribute ENV APP
    Create, read, update, and delete flow policy assignment ENV APP‑O APP
    Create, read, update, and delete grant ENV APP
    Create, read, update, and delete key rotation policy ENV
    Create, read, update, and delete resource ENV APP
    Create, read, update, and delete scope ENV APP
    Create, read, update, and delete sign-on policy assignment ENV APP‑O APP
    Issue, create, read, update, and delete certificate ENV
    Read and update application admin role assignments ENV APP
    Read application CFA‑R
    Read application admin role assignments APP‑O CFA‑R
    Read application catalog ORG ENV APP‑O CFA‑R APP
    Read application secret APP‑O CFA‑R
    Read attribute APP‑O CFA‑R
    Read flow policy assignment CFA‑R
    Read grant APP‑O CFA‑R
    Read key rotation policy CFA‑R
    Read resource APP‑O CFA‑R
    Read resources secret APP‑O CFA‑R
    Read scope APP‑O CFA‑R
    Read sign-on policy assignment CFA‑R
    Read, update, and delete application APP‑O
    Read, update, and delete application secret ENV APP
    Read, update, and delete resources secret ENV APP
    Authentication Create create test device IDA
    Create, read, and delete FIDO device metadata ENV
    Create, read, and delete adaptive access policy assignment ORG ENV APP‑O APP
    Create, read, and delete pairing key IDA
    Create, read, update, and delete FIDO policy ENV
    Create, read, update, and delete OATH token ENV
    Create, read, update, and delete adaptive access policy ORG ENV APP
    Create, read, update, and delete device authentication policy ENV
    Create, read, update, and delete password policy ENV
    Create, read, update, and delete push credentials ENV APP
    Create, read, update, and delete sessions IDA
    Create, read, update, and delete sign-on policy ENV
    Read FIDO device metadata CFA‑R
    Read FIDO policy CFA‑R
    Read MFA settings CFA‑R
    Read OATH job ENV CFA‑R
    Read OATH token CFA‑R
    Read adaptive access policy CFA‑R
    Read adaptive access policy assignment CFA‑R
    Read device authentication policy CFA‑R
    Read pairing key IDA‑R
    Read password policy IDA IDA‑R CFA‑R
    Read push credentials APP‑O CFA‑R
    Read sessions IDA‑R
    Read sign-on policy APP‑O CFA‑R APP
    Read, update, and delete MFA settings ENV
    Authorization Authorize, create, read, and update decision endpoint ENV
    Authorize, create, read, update, and delete decision endpoint ORG
    Create, read, and delete application role assignments ENV IDA
    Create, read, and delete application role entries ENV IDA
    Create, read, test, update, and delete authorization attribute ORG ENV
    Create, read, test, update, and delete authorization condition ORG ENV
    Create, read, test, update, and delete authorization policy ORG ENV
    Create, read, test, update, and delete authorization rule ORG ENV
    Create, read, test, update, and delete authorization service ORG ENV
    Create, read, test, update, and delete entity ORG ENV
    Create, read, update, and delete API services ENV APP
    Create, read, update, and delete application permissions ENV IDA
    Create, read, update, and delete application resources ENV IDA
    Create, read, update, and delete application roles ENV IDA
    Create, read, update, and delete authorization processor ORG ENV
    Create, read, update, and delete authorization statement ORG ENV
    Deploy and read API service deployment ENV APP
    Read API service deployment CFA‑R
    Read API services APP‑O CFA‑R
    Read application entitlements ENV IDA IDA‑R CFA‑R APP
    Read application permissions IDA‑R CFA‑R APP
    Read application resources IDA‑R CFA‑R APP
    Read application role assignments IDA‑R CFA‑R APP
    Read application role entries IDA‑R CFA‑R APP
    Read application roles IDA‑R CFA‑R APP
    Read authorization attribute CFA‑R
    Read authorization condition CFA‑R
    Read authorization policy CFA‑R
    Read authorization processor CFA‑R
    Read authorization rule CFA‑R
    Read authorization service CFA‑R
    Read authorization statement CFA‑R
    Read authorize gateway deployment ORG ENV CFA‑R
    Read decision endpoint CFA‑R
    Read deployment package ORG ENV CFA‑R
    Read entity CFA‑R
    Read policy version ORG ENV CFA‑R
    Read recent decisions ORG ENV CFA‑R
    Read tag CFA‑R
    Read, update, and delete tag ORG ENV
    DaVinci Create, deploy, read, update, and delete DaVinci flows DVA
    Create, read, update, and delete DaVinci UI templates DVA
    Create, read, update, and delete DaVinci applications DVA
    Create, read, update, and delete DaVinci connections DVA
    Create, read, update, and delete DaVinci flow policies DVA
    Create, read, update, and delete DaVinci variables DVA
    Export, read, revert, update, and delete DaVinci flow versions DVA
    Read DaVinci UI templates DVA‑R
    Read DaVinci applications DVA‑R
    Read DaVinci connections DVA‑R
    Read DaVinci connectors DVA DVA‑R
    Read DaVinci events DVA DVA‑R
    Read DaVinci flow policies DVA‑R
    Read DaVinci flow versions DVA‑R
    Read DaVinci flows DVA‑R
    Read DaVinci interaction events DVA DVA‑R
    Read DaVinci stats DVA DVA‑R
    Read DaVinci users DVA‑R
    Read DaVinci variables DVA‑R
    Read access token ENV CFA‑R APP
    Read flow policy ENV APP‑O CFA‑R APP
    Read, update, and delete DaVinci users DVA
    Digital Credentials Create, read, and delete verification session ENV IDA
    Create, read, and update credential issuer profile ENV IDA
    Create, read, update, and delete credential type ENV IDA
    Create, read, update, and delete digital wallet ENV IDA
    Create, read, update, and delete digital wallet application ENV IDA
    Create, read, update, and delete issuance rule ENV IDA
    Create, read, update, and delete verifiable credential ENV IDA
    Read and update staged changes ENV IDA
    Read credential issuer profile IDA‑R CFA‑R
    Read credential type IDA‑R CFA‑R
    Read digital wallet IDA‑R CFA‑R
    Read digital wallet application IDA‑R CFA‑R
    Read issuance rule IDA‑R CFA‑R
    Read staged changes IDA‑R
    Read verifiable credential IDA‑R CFA‑R
    Read verification session IDA‑R CFA‑R
    Directory Authenticate, create, read, update, and delete device IDA
    Create, import, invite, read, update, verify, and delete user IDA
    Create, provision, read, update, and delete group IDA
    Create, read, and delete group membership IDA
    Create, read, and delete group role assignments IDA
    Create, read, and delete user linked accounts IDA
    Create, read, update, and delete accessing device IDA
    Create, read, update, and delete custom roles ORG ROLE
    Create, read, update, and delete population ENV
    Create, read, update, and delete user (SCIM) IDA
    Create, read, update, and delete user association with accessing device IDA
    Force change, read, recover, reset, set, unlock, and validate user password IDA
    Lock and unlock user account IDA
    Read accessing device IDA‑R
    Read and update user role assignments IDA
    Read custom roles ENV IDA APP‑O IDA‑R CFA‑R APP
    Read device IDA‑R
    Read group ENV APP‑O IDA‑R CFA‑R APP
    Read group membership IDA‑R
    Read group provisioning rule sync status ENV IDA IDA‑R CFA‑R
    Read group role assignments IDA‑R
    Read population IDA IDA‑R CFA‑R APP
    Read schema IDA DVA APP‑O IDA‑R CFA‑R DVA‑R APP
    Read schema (SCIM) IDA IDA‑R
    Read session IDA IDA‑R
    Read user IDA‑R
    Read user (LDAP gateway) IDA IDA‑R
    Read user (SCIM) IDA‑R
    Read user association with accessing device IDA‑R
    Read user linked accounts IDA‑R
    Read user password IDA‑R
    Read user role assignments ENV IDA‑R CFA‑R APP
    Read user target store sync status ENV IDA IDA‑R CFA‑R
    Read, update, and delete schema ENV
    Reset user quota IDA
    Update user MFA-bypass IDA
    Update user MFA-enabled IDA
    Update user enabled IDA
    Update user identity provider IDA
    Update user verify status IDA
    Validate user password (LDAP gateway) IDA
    Identity Verification Create identity record matching ENV IDA
    Create, get, update, and delete document ENV IDA
    Create, read, update, and delete verify policy ENV IDA
    Create, read, update, and delete verify transactions IDA
    Create, read, update, and delete voice phrase ENV IDA
    Create, read, update, and delete voice phrase content ENV IDA
    Get and delete reference data IDA
    Get, update, and delete verified user data IDA
    Read verify policy IDA‑R CFA‑R
    Read verify transactions IDA‑R
    Read voice phrase IDA‑R CFA‑R
    Read voice phrase content IDA‑R CFA‑R
    Integrations Check connection ENV
    Create and get revision ENV
    Create and update provisioning sync orchestration ENV
    Create, read, update, and delete gateway ENV
    Create, read, update, and delete identity provider ENV APP
    Execute direct LDAP IDA
    Execute, read, and validate PingID migration ENV
    Get connection sensitive configuration ENV
    Read PingID migration CFA‑R
    Read gateway CFA‑R
    Read gateway role assignments CFA‑R
    Read identity provider IDA IDA‑R CFA‑R
    Read mapping CFA‑R
    Read provisioning plan CFA‑R
    Read provisioning rule CFA‑R
    Read provisioning store CFA‑R
    Read, update, and delete gateway role assignments ENV
    Read, update, and delete mapping ENV
    Read, update, and delete provisioning plan ENV
    Read, update, and delete provisioning rule ENV
    Read, update, and delete provisioning store ENV
    Validate Kerberos IDA
    Validate PingID migration ORG
    Monitoring Create, read, update, and delete alert delivery channel ENV
    Create, read, update, and delete subscription ENV
    Read PingID activity IDA IDA‑R
    Read alert delivery channel CFA‑R
    Read audit ENV IDA IDA‑R CFA‑R
    Read authentication ORG ENV IDA IDA‑R CFA‑R APP
    Read dashboard ORG ENV IDA IDA‑R CFA‑R APP
    Read subscription CFA‑R
    Read template ORG ENV IDA IDA‑R CFA‑R APP
    Read user demographics ORG ENV IDA IDA‑R CFA‑R APP
    Organization Create and read bootstrap ORG
    Create and read deployment ORG ENV
    Create, promote, read, update, and delete environment ORG
    Promote, read, and update environment ENV
    Read console access ORG ENV IDA DVA IDA‑R CFA‑R DVA‑R APP
    Read deployment IDA DVA IDA‑R CFA‑R DVA‑R ROLE APP
    Read environment IDA DVA APP‑O IDA‑R CFA‑R DVA‑R ROLE APP
    Read license ORG ENV IDA DVA APP‑O IDA‑R CFA‑R DVA‑R ROLE APP
    Read organization ORG ENV IDA DVA APP‑O IDA‑R CFA‑R DVA‑R ROLE APP
    Other Create and update advanced identity cloud orchestration ORG ENV
    Create, read, and update configuration ENV
    Create, read, update, and delete PingOne for Enterprise orchestration ORG
    Create, read, update, and delete pingintelligence orchestration ORG
    Read PingOne for Enterprise orchestration CFA‑R APP
    Read and update PingOne for Enterprise orchestration ENV
    Read and update configuration APP
    Read and update pingintelligence orchestration ENV
    Read configuration CFA‑R
    Read getting started flows ENV CFA‑R APP
    Read pingintelligence orchestration CFA‑R APP
    Settings Create key ORG
    Create, read, update, and delete custom domain ENV
    Create, read, update, and delete email domain ENV
    Create, read, update, and delete key ENV
    Display environment overview ORG ENV IDA DVA APP‑O IDA‑R CFA‑R DVA‑R ROLE APP
    Display environment properties ORG ENV IDA DVA APP‑O IDA‑R CFA‑R DVA‑R ROLE APP
    Read administrator security configuration IDA IDA‑R CFA‑R APP
    Read and update administrator security configuration ORG ENV
    Read certificate IDA APP‑O IDA‑R CFA‑R APP
    Read custom domain APP‑O CFA‑R APP
    Read email domain CFA‑R
    Read key APP‑O CFA‑R APP
    Update environment license ORG
    Update mutable properties ORG
    Threat Protection Create and read exploration ORG ENV IDA IDA‑R CFA‑R APP
    Create feedback ENV IDA
    Create prediction IDA
    Create, create, read, and update evaluation IDA
    Create, read, update, and delete policy ENV
    Create, read, update, and delete predictor ENV
    Read evaluation IDA‑R
    Read policy IDA IDA‑R CFA‑R
    Read predictor IDA IDA‑R CFA‑R
    User Experience Create and read image APP‑O
    Create notification ENV
    Create, read, and delete image ENV IDA APP
    Create, read, and update OAuth consent IDA
    Create, read, update, and delete agreement ENV
    Create, read, update, and delete branding themes ENV
    Create, read, update, and delete form ENV DVA
    Create, read, update, and delete language ENV
    Create, read, update, and delete notifications policy ENV
    Create, read, update, and delete template content ENV
    Create, read, update, and delete user consent IDA
    Read OAuth consent IDA‑R
    Read agreement CFA‑R
    Read and update branding settings ENV
    Read and update language DVA
    Read branding settings DVA CFA‑R DVA‑R APP
    Read branding themes DVA CFA‑R DVA‑R APP
    Read end user UI configurations ENV CFA‑R APP
    Read form CFA‑R DVA‑R APP
    Read image IDA‑R CFA‑R
    Read language CFA‑R DVA‑R
    Read notification template ENV CFA‑R
    Read notifications policy CFA‑R
    Read notifications settings CFA‑R
    Read quota ENV CFA‑R
    Read reCAPTCHA V2 configuration CFA‑R DVA‑R APP
    Read template content CFA‑R
    Read user consent IDA‑R
    Read, update, and delete notifications settings ENV
    Read, update, and delete reCAPTCHA V2 configuration ENV DVA

    Advanced Identity Cloud Support

    Category Permission AIC‑SUPER AIC‑TENANT
    Organization Read console access AIC‑SUPER AIC‑TENANT
    Read deployment AIC‑SUPER AIC‑TENANT
    Read environment AIC‑SUPER AIC‑TENANT
    Read license AIC‑SUPER AIC‑TENANT
    Read organization AIC‑SUPER AIC‑TENANT
    Other Admin advanced identity cloud super admin AIC‑SUPER
    Admin advanced identity cloud tenant admin AIC‑SUPER AIC‑TENANT
    Settings Display environment overview AIC‑SUPER AIC‑TENANT
    Display environment properties AIC‑SUPER AIC‑TENANT

    PingOne Permissions by Identifier

    A permission identifier is a three-part, colon-delimited string that represents the category, action, and resource to which the permission applies.

    The Special column indicates special handling of certain permissions:

    • Essential: Start building a new custom role with the minimum set of permissions needed for the role to be usable.

    • Sensitive: The permission either provides access to sensitive information, such as personal user data, or allows the bearer to perform important actions that could negatively impact the organization, such as deleting an environment.

    Identifier Permission Special
    licensing:read:license Read license information for the organization. essential
    orgmgt:read:deployment Read deployments for other Ping products in the PingOne environment. These other products might require additional configuration outside of PingOne. essential
    orgmgt:read:environment Read a list of the environments that a user belongs to. Environments are the primary subdivision of an organization. essential
    orgmgt:read:organization Read the organization that a user belongs to. A user can belong to one organization only. The organization is the top-level identifier in PingOne. essential
    admin:update:config Update the administrator security settings used for accessing the admin console. sensitive
    applications:issue:certificate Issue a new KDC certificate sensitive
    applications:read:secret Read the client secret for an application. Client secrets are used to authenticate an application with PingOne. sensitive
    applications:update:secret Create a new client secret for an application. Client secrets are used to authenticate an application with PingOne. sensitive
    applications:delete:secret Revoke the previous client secret for an application before it expires. Client secrets are used to authenticate an application with PingOne and can be revoked when a new secret is generated. sensitive
    certmgt:create:certificate Create a certificate. Certificates are security credentials that PingOne uses for encryption and signing. sensitive
    certmgt:read:certificate Read the metadata for a certificate and export the certificate as an X509 certificate. Certificates are security credentials that PingOne uses for encryption and signing. sensitive
    certmgt:update:certificate Update a certificate. Updates include making a certificate default and reassigning a certificate to an application. Certificates are security credentials that PingOne uses for encryption and signing. sensitive
    certmgt:delete:certificate Delete a certificate. Certificates are security credentials that PingOne uses for encryption and signing. sensitive
    certmgt:create:key Create a new key pair. Key pairs are security credentials that PingOne uses for encryption and signing. sensitive
    certmgt:update:key Update a key pair. Updates include making a key pair default and reassigning a key pair to an application. Key pairs are security credentials that PingOne uses for encryption and signing. sensitive
    certmgt:delete:key Delete a key pair. Key pairs are security credentials that PingOne uses for encryption and signing. sensitive
    dir:forceChange:userPassword Force a user to change their password the next time they sign on. The password state is MUST_CHANGE_PASSWORD. sensitive
    dir:recover:userPassword Reset a user's password using a recovery code. Send a recovery code. sensitive
    dir:reset:userPassword Reset a user's password without requiring a recovery code. sensitive
    dir:set:userPassword Set a user's clear text or pre-encoded password and set a user's password authority. sensitive
    dir:unlock:userPassword Unlock a user's password. The password state is PASSWORD_LOCKED_OUT. sensitive
    mfa:create:device Create an MFA device. sensitive
    mfa:update:device Update an MFA device. sensitive
    mfa:delete:device Delete an MFA device. sensitive
    orgmgt:create:environment Create an environment to include a set of services and capabilities. Define the name and description, and include license information. Environments are the primary subdivision of an organization. sensitive
    orgmgt:delete:environment Delete an environment and all of its associated resources, such as applications, users, and branding. Environments are the primary subdivision of an organization. sensitive
    permissions:update:applicationRoleAssignments Assign or revoke admin roles for an application scope. Roles are used by worker applications only. sensitive
    permissions:update:gatewayRoleAssignments Add roles and the associated permissions associated with a gateway scope. The gateway scope defines the attributes that can be accessed in the external LDAP directory. sensitive
    permissions:delete:gatewayRoleAssignments Remove roles and the associated permissions associated with a gateway scope. The gateway scope defines the attributes that can be accessed in the external LDAP directory. sensitive
    permissions:create:groupRoleAssignments Assign an admin role to a group. sensitive
    permissions:delete:groupRoleAssignments Remove an admin role from a group. sensitive
    permissions:create:roles Create a custom role for the environment. sensitive
    permissions:read:roles Read a list of custom roles for the environment. sensitive
    permissions:update:roles Update the permissions that are included in a custom role for the environment. sensitive
    permissions:delete:roles Remove a custom role from the environment. sensitive
    permissions:update:userRoleAssignments Update admin roles that are assigned to a user, including the role permissions. sensitive
    resources:read:secret Read the client secret for a resource. Client secrets are used to authenticate a resource with PingOne. sensitive
    resources:update:secret Create a new client secret for a resource. Client secrets are used to authenticate a resource with PingOne. sensitive
    resources:delete:secret Revoke the previous client secret for an application resource before it expires. Client secrets are used to authenticate a resource with PingOne and can be revoked when a new secret is generated. sensitive
    admin:read:config Read the administrator security settings used for accessing the admin console.
    agreements:create:agreement Create an agreement that users must consent to as part of an authentication policy or flow.
    agreements:read:agreement Read agreements that users must consent to as part of an authentication policy or flow.
    agreements:update:agreement Update an agreement that users must consent to as part of an authentication policy or flow.
    agreements:delete:agreement Delete an agreement that users must consent to as part of an authentication policy or flow.
    agreements:create:oauthConsent Create a record of the user's consent to share their information with an OAuth application during an authentication flow.
    agreements:read:oauthConsent Read the OAuth consent history for a user.
    agreements:update:oauthConsent Update the recorded date for the user's consent to an OAuth application request for personal information during an authentication flow.
    agreements:create:userConsent Consent to an agreement on behalf of a particular user.
    agreements:read:userConsent Read the consent history for a user, including agreement names, language, and date of consent.
    agreements:update:userConsent Require a user to re-consent to an agreement when the agreement has been updated.
    agreements:delete:userConsent Delete consent to an agreement on behalf of a particular user.
    alerting:create:channel Create an alert channel to define the types of events that will trigger an alert and to list email addresses where the alerts will be sent.
    alerting:read:channel Read alert channels to view the types of events that will trigger an alert and the list of email addresses where the alerts will be sent.
    alerting:update:channel Update an alert channel to change the types of events that will trigger an alert or to change the email addresses where the alerts will be sent.
    alerting:delete:channel Delete an alert channel to stop sending alerts about events to a list of email addresses.
    applicationRoles:read:applicationEntitlement Query a user's entitled application permissions, which control the actions the user can take in applications and APIs. Application permissions are defined on resources and assigned through application roles.
    applicationRoles:create:applicationPermission Create permissions that represent actions that can be taken on resources in external applications.
    applicationRoles:read:applicationPermission List application permissions and read permission details, including permission descriptions, actions, and resources.
    applicationRoles:update:applicationPermission Update details for application permissions, including permission actions and descriptions.
    applicationRoles:delete:applicationPermission Delete application permissions.
    applicationRoles:create:applicationResource Create resources that represent protected features in external applications.
    applicationRoles:read:applicationResource List application resources and read resource details, including resource names and descriptions.
    applicationRoles:update:applicationResource Update details for application resources, including resource names and descriptions.
    applicationRoles:delete:applicationResource Delete application resources.
    applicationRoles:create:applicationRole Create roles that group permissions for external applications by function.
    applicationRoles:read:applicationRole List application roles and read role details, including role names and descriptions.
    applicationRoles:update:applicationRole Update details for application roles, including role names and descriptions.
    applicationRoles:delete:applicationRole Delete application roles.
    applicationRoles:create:applicationRoleAssignment Assign application roles to users to grant the associated permissions for actions in external applications.
    applicationRoles:read:applicationRoleAssignment Read application roles that are assigned to a user, including the role permissions.
    applicationRoles:delete:applicationRoleAssignment Remove application role assignments from users to revoke the associated permissions for actions in external applications.
    applicationRoles:create:applicationRoleEntry Add permissions for external applications to application roles.
    applicationRoles:read:applicationRoleEntry List permissions for an application role.
    applicationRoles:delete:applicationRoleEntry Delete permissions from application roles.
    applications:create:application Create an application in the environment.
    applications:read:application Read the settings for an application in the environment.
    applications:update:application Update the settings for an application in the environment.
    applications:delete:application Delete an application from the environment.
    applications:create:flowPolicyAssignment Assign DaVinci policies to PingOne applications. When assigned, a DaVinci policy controls which DaVinci flow a PingOne application uses for authentication.
    applications:read:flowPolicyAssignment Read the assigned DaVinci policies for any PingOne application.
    applications:update:flowPolicyAssignment Update the policy order for DaVinci policies assigned to PingOne applications. A PingOne application applies policies in their listed order from top to bottom.
    applications:delete:flowPolicyAssignment Unassign DaVinci policies from PingOne applications. When unassigned, a DaVinci policy no longer has control over the authentication experience for the PingOne application.
    applications:create:grant Assign a resource scope to an application. Resource scopes define application access to user details, such as name and email address.
    applications:read:grant Read the resource scope that is assigned to an application. Resource scopes define application access to user details, such as name and email address.
    applications:update:grant Change the resource scopes that are assigned to an application. Resource scopes define application access to user details, such as name and email address.
    applications:delete:grant Delete an assigned resource scope from an application. Resource scopes define application access to user details, such as name and email address.
    applications:create:pushCredentials Create push credentials for a mobile application.
    applications:read:pushCredentials Read push credentials for a mobile application.
    applications:update:pushCredentials Update push credentials for a mobile application.
    applications:delete:pushCredentials Delete push credentials for a mobile application.
    applications:create:signOnPolicyAssignment Assign an authentication policy that defines the sign-on requirements used to access an application.
    applications:read:signOnPolicyAssignment Read authentication policies that are assigned to an application. Authentication policies define the sign-on requirements used to access an application.
    applications:update:signOnPolicyAssignment Update the authentication policy that is assigned to an application to change the sign-on requirements used to access an application.
    applications:delete:signOnPolicyAssignment Delete an assigned authentication policy from an application. Authentication policies define the sign-on requirements used to access an application.
    audit_reporting:read:activity Read Audit Activity
    authn:create:sessions Create a session for a user when they complete authentication during sign-on.
    authn:read:sessions Read all sessions for a particular user.
    authn:update:sessions Update a user session when the authentication process or API request has a valid session ID cookie.
    authn:delete:sessions Delete a recent user session to sign the user out of PingOne. For example, you can delete a session if you detect suspicious activity.
    authn:create:signOnPolicy Create an authentication policy, which defines how user identities are verified at sign-on.
    authn:read:signOnPolicy Read authentication policies, which define how user identities are verified at sign-on.
    authn:update:signOnPolicy Update an authentication policy to change how user identities are verified at sign-on.
    authn:delete:signOnPolicy Delete an authentication policy.
    authz:create:adaptiveTrustPolicy Create an adaptive access policy. Adaptive access policies define contextual rules for access to applications.
    authz:read:adaptiveTrustPolicy Read configuration details for adaptive access policies. Adaptive access policies define contextual rules for access to applications.
    authz:update:adaptiveTrustPolicy Update an adaptive access policy. Adaptive access policies define contextual rules for access to applications.
    authz:delete:adaptiveTrustPolicy Delete an adaptive access policy. Adaptive access policies define contextual rules for access to applications.
    authz:create:adaptiveTrustPolicyAssignment Assign an adaptive access policy to an application. Adaptive access policies define contextual rules for access to applications.
    authz:read:adaptiveTrustPolicyAssignment Read adaptive access policy assignments for an application. Policy assignments control which policies the application uses for adaptive access.
    authz:delete:adaptiveTrustPolicyAssignment Delete adaptive access policy assignments from an application. Policy assignments control which policies the application uses for adaptive access.
    authz:create:apiServer Create an API service and associated operations, which represent an HTTP API with access control handled by PingOne Authorize.
    authz:read:apiServer Read details for an API service and its associated operations, including the name, base URLs, and directory and token source.
    authz:update:apiServer Update details for an API service and its associated operations, including the name, base URLs, and basic rules.
    authz:delete:apiServer Delete an API service and its associated operations, decision endpoint, and policy tree.
    authz:deploy:apiServerDeployment Deploy API service configuration updates and policies to the API service's decision endpoint.
    authz:read:apiServerDeployment Read an API service's deployment status.
    authz:create:authorizationAttribute Create an authorization attribute in the Trust Framework. Authorization attributes provide contextual information used in authorization decisions.
    authz:read:authorizationAttribute Read configuration details for authorization attributes in the Trust Framework. Authorization attributes provide contextual information used in authorization decisions.
    authz:test:authorizationAttribute Test an authorization attribute in the Trust Framework. Authorization attributes provide contextual information used in authorization decisions.
    authz:update:authorizationAttribute Update an authorization attribute in the Trust Framework. Authorization attributes provide contextual information used in authorization decisions.
    authz:delete:authorizationAttribute Delete an authorization attribute from the Trust Framework. Authorization attributes provide contextual information used in authorization decisions.
    authz:create:authorizationCondition Create an authorization condition in the Trust Framework. Authorization conditions use comparisons to define authorization policy logic.
    authz:read:authorizationCondition Read configuration details for authorization conditions in the Trust Framework. Authorization conditions use comparisons to define authorization policy logic.
    authz:test:authorizationCondition Test an authorization condition in the Trust Framework. Authorization conditions use comparisons to define authorization policy logic.
    authz:update:authorizationCondition Update an authorization condition in the Trust Framework. Authorization conditions use comparisons to define authorization policy logic.
    authz:delete:authorizationCondition Delete an authorization condition from the Trust Framework. Authorization conditions use comparisons to define authorization policy logic.
    authz:create:authorizationPolicy Create an authorization policy. Authorization policies define the context and logic used to control access to application resources.
    authz:read:authorizationPolicy Read configuration details for authorization policies. Authorization policies define the context and logic used to control access to application resources.
    authz:test:authorizationPolicy Test an authorization policy. Authorization policies define the context and logic used to control access to application resources.
    authz:update:authorizationPolicy Update an authorization policy. Authorization policies define the context and logic used to control access to application resources.
    authz:delete:authorizationPolicy Delete an authorization policy. Authorization policies define the context and logic used to control access to application resources.
    authz:create:authorizationProcessor Create an authorization processor in the Trust Framework. Authorization processors transform data returned from authorization attributes and services.
    authz:read:authorizationProcessor Read configuration details for authorization processors in the Trust Framework. Authorization processors transform data returned from authorization attributes and services.
    authz:update:authorizationProcessor Update an authorization processor in the Trust Framework. Authorization processors transform data returned from authorization attributes and services.
    authz:delete:authorizationProcessor Delete an authorization processor from the Trust Framework. Authorization processors transform data returned from authorization attributes and services.
    authz:create:authorizationRule Create an authorization rule. Authorization rules use conditions or in-line comparisons to define authorization policy logic.
    authz:read:authorizationRule Read configuration details for authorization rules. Authorization rules use conditions or in-line comparisons to define authorization policy logic.
    authz:test:authorizationRule Test an authorization rule. Authorization rules use conditions or in-line comparisons to define authorization policy logic.
    authz:update:authorizationRule Update an authorization rule. Authorization rules use conditions or in-line comparisons to define authorization policy logic.
    authz:delete:authorizationRule Delete an authorization rule. Authorization rules use conditions or in-line comparisons to define authorization policy logic.
    authz:create:authorizationService Create an authorization service in the Trust Framework. Authorization services connect to data sources used in authorization decisions.
    authz:read:authorizationService Read configuration details for authorization services in the Trust Framework. Authorization services connect to data sources used in authorization decisions.
    authz:test:authorizationService Test an authorization service in the Trust Framework. Authorization services connect to data sources used in authorization decisions.
    authz:update:authorizationService Update an authorization service in the Trust Framework. Authorization services connect to data sources used in authorization decisions.
    authz:delete:authorizationService Delete an authorization service from the Trust Framework. Authorization services connect to data sources used in authorization decisions.
    authz:create:authorizationStatement Create an authorization statement. Authorization statements provide additional processing instructions in authorization decisions.
    authz:read:authorizationStatement Read configuration details for authorization statements. Authorization statements provide additional processing instructions in authorization decisions.
    authz:update:authorizationStatement Update an authorization statement. Authorization statements provide additional processing instructions in authorization decisions.
    authz:delete:authorizationStatement Delete an authorization statement. Authorization statements provide additional processing instructions in authorization decisions.
    authz:read:authorizeDeployment Read PingOne Authorize Gateway Deployment
    authz:authorize:decisionendpoint Make a decision request to a decision endpoint, initiating evaluation of policies deployed to the endpoint.
    authz:create:decisionendpoint Create a decision endpoint, which provides an environment for authorization policy deployment.
    authz:read:decisionendpoint Read details for a decision endpoint, including its name, description, policy version deployed, and whether recent decisions are recorded.
    authz:update:decisionendpoint Update details for a decision endpoint, including its name, description, policy version deployed, and whether recent decisions are recorded.
    authz:delete:decisionendpoint Delete a decision endpoint and any recent decisions stored for the endpoint.
    authz:read:deploymentpackage Read the deployment package of policies and Trust Framework definitions associated with a specific authorization version.
    authz:create:entity Create an authorization service, attribute, condition, processor, policy set, policy, rule, statement, or target.
    authz:read:entity Read details about an authorization service, attribute, condition, processor, policy set, policy, rule, statement, or target.
    authz:test:entity Test an authorization service, attribute, condition, policy set, policy, or library rule.
    authz:update:entity Update an authorization service, attribute, condition, processor, policy set, policy, rule, statement, or target.
    authz:delete:entity Delete an authorization service, attribute, condition, processor, policy set, policy, rule, statement, or target.
    authz:read:recentdecisions Read details about the decision flow and elements used in recent decisions for a decision endpoint.
    authz:read:tag Read an authorization version name.
    authz:update:tag Create or update an authorization version name.
    authz:delete:tag Delete an authorization version name.
    authz:read:version Read details about an authorization version, including the entity that changed, the date and time, and the user who made the change.
    bootstrap:create:bootstrap Start a bootstrap execution for provisioning.
    bootstrap:read:bootstrap Check bootstrap execution status by invoking the GET endpoint.
    branding:update:branding Create and update branding
    branding:delete:branding Delete branding
    branding:read:brandingSettings Read the company name and logo for an environment.
    branding:update:brandingSettings Update the company name and logo for an environment.
    branding:create:customDomain Create a custom domain for the environment to personalize the user-facing PingOne service URLs.
    branding:read:customDomain Read the custom domain for the environment and see the corresponding custom service URLs. If enabled, custom domains replace pingone in the address bar.
    branding:update:customDomain Update the custom domain for the environment to renew the SSL certificate.
    branding:delete:customDomain Delete a custom domain from the environment to stop using it in the user-facing PingOne service URLs.
    branding:create:theme Create a theme to customize the colors and images used on your registration pages, sign-on pages, and verification pages for an environment.
    branding:read:theme Read the themes available for an environment. Themes dictate the colors and images used on the registration pages, sign-on pages, and verification pages for an environment.
    branding:update:theme Update a theme in an environment. Themes dictate the colors and images used on the registration pages, sign-on pages, and verification pages for an environment.
    branding:delete:theme Delete a theme from an environment. Themes dictate the customization of the colors and images used on the registration pages, sign-on pages, and verification pages for an environment.
    certmgt:read:key Read the metadata for a key pair and download it as an X509 certificate. Key pairs are security credentials that PingOne uses for encryption and signing.
    certmgt:create:krp Create a new key rotation policy in the environment. PingOne uses key rotation to automatically generate new cryptographic keys at a particular interval.
    certmgt:read:krp Read a list of key rotation policies in the environment. PingOne uses key rotation to automatically generate new cryptographic keys at a particular interval.
    certmgt:update:krp Update a key rotation policy in the environment. PingOne uses key rotation to automatically generate new cryptographic keys at a particular interval.
    certmgt:delete:krp Delete a key rotation policy from the environment. PingOne uses key rotation to automatically generate new cryptographic keys at a particular interval.
    console:display:environmentOverview View the environment overview page in the administrator console. This permission only affects visibility in the administrator console and not API access.
    console:display:environmentProperties View the environment properties page in the administrator console. This permission only affects visibility in the administrator console and not API access.
    credentialsIssuance:create:credentialType Create a credential type for an environment. A credential type defines a template that is used when creating or updating a user credential.
    credentialsIssuance:read:credentialType Read a credential type for an environment. A credential type defines a template that is used when creating or updating a user credential.
    credentialsIssuance:update:credentialType Update a credential type for an environment. A credential type defines a template that is used when creating or updating a user credential.
    credentialsIssuance:delete:credentialType Delete a credential type for an environment. A credential type defines a template that is used when creating or updating a user credential.
    credentialsIssuance:create:credentials Create a credential. Credentials allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation.
    credentialsIssuance:read:credentials Read a credential. Credentials allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation..
    credentialsIssuance:update:credentials Update a credential. Credentials allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation.
    credentialsIssuance:delete:credentials Delete a credential. Credentials allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation.
    credentialsIssuance:create:digitalWallet Create a digital wallet for a user. A digital wallet links an instance of a digital wallet application to a user.
    credentialsIssuance:read:digitalWallet Read a digital wallet for a user. A digital wallet links an instance of a digital wallet application to a user.
    credentialsIssuance:update:digitalWallet Updated a digital wallet for a user. A digital wallet links an instance of a digital wallet application to a user.
    credentialsIssuance:delete:digitalWallet Delete a digital wallet for a user. A digital wallet links an instance of a digital wallet application to a user.
    credentialsIssuance:create:digitalWalletApplication Create a digital wallet application. A digital wallet application defines the relationship between a user's digital wallet and a customer's PingOne application.
    credentialsIssuance:read:digitalWalletApplication Read a digital wallet application. A digital wallet application defines the relationship between a user's digital wallet and a customer's PingOne application.
    credentialsIssuance:update:digitalWalletApplication Update a digital wallet application. A digital wallet application defines the relationship between a user's digital wallet and a customer's PingOne application.
    credentialsIssuance:delete:digitalWalletApplication Delete a digital wallet application. A digital wallet application defines the relationship between a user's digital wallet and a customer's PingOne application.
    credentialsIssuance:create:issuanceRule Create an issuance rule for a credential type. Issuance rules are used to issue credentials to a specified group, population or SCIM filter.
    credentialsIssuance:read:issuanceRule Read an issuance rule for a credential type. Issuance rules are used to issue credentials to a specified group, population or SCIM filter.
    credentialsIssuance:update:issuanceRule Update an issuance rule for a credential type. Issuance rules are used to issue credentials to a specified group, population or SCIM filter.
    credentialsIssuance:delete:issuanceRule Delete an issuance rule for a credential type. Issuance rules are used to issue credentials to a specified group, population or SCIM filter.
    credentialsIssuance:create:issuerProfile Create the environment profile used for issuing user credentials.
    credentialsIssuance:read:issuerProfile Read the environment profile used for issuing user credentials.
    credentialsIssuance:update:issuerProfile Update the environment profile used for issuing user credentials.
    credentialsIssuance:read:stagedChanges Read staged changes for an issuance rule. Staged changes show actions for an issuance rule that are staged for execution.
    credentialsIssuance:update:stagedChanges Update staged changes for an issuance rule. Allows for refreshing and applying of staged actions for an issuance rule.
    credentialsVerification:create:presentationSession Create a Verification Session. Verification Sessions allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation.
    credentialsVerification:read:presentationSession Read a Verification Session. Verification Sessions allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation.
    credentialsVerification:delete:presentationSession Delete a Verification Session. Verification Sessions allow providers of services to verify authenticity and accuracy of issuance and data integrity at the time of presentation.
    davinci:create:applications Create DaVinci applications
    davinci:read:applications Read DaVinci applications
    davinci:update:applications Update DaVinci applications
    davinci:delete:applications Delete DaVinci applications
    davinci:create:connections Create a new DaVinci connector for an environment and make it available for use in all DaVinci flows.
    davinci:read:connections Read a list of all connectors added to an environment, including their configurations and containing DaVinci flows.
    davinci:update:connections Update the environment-level configuration of a connector instance. These changes also affect any use of the connector in DaVinci flows.
    davinci:delete:connections Delete a connector instance from an environment. This operation renders the connector instance non-functional in DaVinci flows.
    davinci:read:connectors Read DaVinci connectors
    davinci:create:constructs Create variables of any available scope in an environment or using the Variables connector in a DaVinci flow.
    davinci:read:constructs Read all variables and their values across the environment and within DaVinci flows.
    davinci:update:constructs Update any variables across the environment and within DaVinci flows.
    davinci:delete:constructs Delete any variables across the environment and within DaVinci flows.
    davinci:create:dvFlows Create or import DaVinci flows in one or more environments. Add new connectors during the import process.
    davinci:deploy:dvFlows Publish versions of DaVinci flows to make them available for use in DaVinci applications.
    davinci:read:dvFlows Read all DaVinci flows and their internal configurations. Also allows you to export flows.
    davinci:update:dvFlows Update the configuration and design of DaVinci flows and add, configure, or remove their subcomponents at the flow level.
    davinci:delete:dvFlows Delete existing DaVinci flows.
    davinci:read:dvUsers Read DaVinci users. DaVinci users are end users created during a DaVinci flow and stored in DaVinci.
    davinci:update:dvUsers Update users in DaVinci. DaVinci users are end users created during a DaVinci flow and stored in DaVinci.
    davinci:delete:dvUsers Delete users from DaVinci. DaVinci users are end users created during a DaVinci flow and stored in DaVinci.
    davinci:read:events Read auditing information for the admin portal. This includes all events that generate an audit log entry, including the creation or modification of a flow, flow policy, or connector.
    davinci:create:flowPolicies Create DaVinci flow policies
    davinci:read:flowPolicies Read DaVinci flow policies
    davinci:update:flowPolicies Update DaVinci flow policies
    davinci:delete:flowPolicies Delete DaVinci flow policies
    davinci:export:flowVersions Export DaVinci flow versions
    davinci:read:flowVersions Read DaVinci flow versions
    davinci:revert:flowVersions Revert DaVinci flow versions
    davinci:update:flowVersions Update DaVinci flow versions
    davinci:delete:flowVersions Delete DaVinci flow versions
    davinci:read:interactionEvents Read DaVinci flow analytics. Flow analytics display information about flow executions, including the nodes used, inputs, and outputs.
    davinci:read:stats Read administrator statistics about the admin portal. This includes the UI dashboard summary and data about the creation and use of flows, connectors, variables, and users.
    davinci:create:uiTemplates Create user interface templates in DaVinci. UI templates can be used in a DaVinci flow to match your company style and branding.
    davinci:read:uiTemplates Read user interface templates in DaVinci. UI templates can be used in DaVinci flows to match your company style and branding.
    davinci:update:uiTemplates Update user interface templates in DaVinci. UI templates can be used in DaVinci flows to match your company style and branding.
    davinci:delete:uiTemplates Delete user interface templates from DaVinci. The UI template can no longer be used in DaVinci flows.
    devices:create:seenDevice Create/Update accessing device
    devices:read:seenDevice Read accessing device
    devices:update:seenDevice Update accessing device
    devices:delete:seenDevice Delete accessing device
    devices:create:userSeenDevice Create user association with accessing device
    devices:read:userSeenDevice Read user association with accessing device
    devices:update:userSeenDevice Update user association with accessing device
    devices:delete:userSeenDevice Delete user association with accessing device
    dir:create:group Create a group in the environment. Groups are used to organize a collection of user identities.
    dir:provision:group Create Provisionable Group
    dir:read:group Read a group in the environment. Groups are used to organize a collection of user identities.
    dir:update:group Update a group, including name, description, and user filter, which defines dynamic group membership. Adding users directly requires the Group Membership permission.
    dir:delete:group Delete a group from the environment. Groups are used to organize a collection of user identities.
    dir:create:groupMembership Add a user to a group manually, rather than dynamically.
    dir:read:groupMembership Read the group membership for a user.
    dir:delete:groupMembership Delete a user or subgroup from a group.
    dir:read:groupSyncedRules get group's provisioning rule sync status
    dir:create:passwordPolicy Create a password policy for the environment. A password policy dictates the strength and complexity requirements for a password or passphrase.
    dir:read:passwordPolicy Read a list of password policies for the environment. A password policy dictates the strength and complexity requirements for a password or passphrase.
    dir:update:passwordPolicy Update a password policy for the environment. A password policy dictates the strength and complexity requirements for a password or passphrase.
    dir:delete:passwordPolicy Delete a password policy from the environment. A password policy dictates the strength and complexity requirements for a password or passphrase.
    dir:create:population Create a population in the environment. A population defines a set of users, and a user can belong to one population only.
    dir:read:population Read a list of populations in the environment. A population defines a set of users, and a user can belong to one population only.
    dir:update:population Update a population, including name and description, password policy, and population members. A population defines a set of users, and a user can belong to one population only.
    dir:delete:population Delete a population from the environment. A population defines a set of users, and a user can belong to one population only.
    dir:read:schema Read the schema for the environment, including its attributes. A schema defines the user attributes in the environment.
    dir:update:schema Update a schema, including creating, updating, and deleting attributes. A schema defines the user attributes in the environment.
    dir:delete:schema Delete a schema from the environment. A schema defines the user attributes in the environment.
    dir:create:user Create a user in the environment.
    dir:import:user Import users into the PingOne Directory. Imported users can include a password value.
    dir:invite:user Invite users
    dir:read:user Read a list of users in the environment.
    dir:update:user Update a user account, including name, email address, and other attributes.
    dir:verify:user Verify a user using a verification code. Send verification codes. Verify a user's email address and send a verification email.
    dir:delete:user Delete a user from the environment.
    dir:lock:userAccount (Probably best not to document publicly)
    dir:unlock:userAccount Unlock a user account. Locked accounts cannot sign on to PingOne.
    dir:update:userEnabled Enable or disable a user. Disabled users cannot sign on to PingOne.
    dir:update:userIdentityProvider Define the authoritative identity provider for a user. An authoritative identity provider has authority over user records and credentials.
    dir:create:userLinkedAccounts Create a linked account for a user. A linked account is tied to a third-party identity provider for authentication.
    dir:read:userLinkedAccounts Read accounts linked to a user. A linked account is tied to a third-party identity provider for authentication.
    dir:delete:userLinkedAccounts Delete a linked account for a user. A linked account is tied to a third-party identity provider for authentication.
    dir:update:userMfaBypass Specify an MFA bypass period for a user. The user will not be prompted to carry out MFA until after this period expires.
    dir:update:userMfaEnabled Update the mfaEnabled status for a user. Specify whether MFA should be enabled for a user.
    dir:read:userPassword Read a user's password state. The password state values can include OK, PASSWORD_LOCKED_OUT, and PASSWORD_EXPIRED.
    dir:validate:userPassword Validate a user's password.
    dir:read:userSyncedStores get user's target store sync status
    dir:update:userVerifyStatus Update a user's verification status.
    enduseruiconfig:read:configs View the Self Service and Application Portal pages.
    externalServices:create:externalService Create an external service
    externalServices:invoke:externalService Invoke an external service request
    externalServices:read:externalService Read a external service(s)
    externalServices:update:externalService Update an external service
    externalServices:delete:externalService Delete an external service
    externalServices:read:secrets Read external service secrets
    externalServices:update:secrets Update external service secrets
    flowPolicies:read:flowPolicy Read all DaVinci policies that are configured for use with PingOne applications.
    formBuilder:create:form Create a DaVinci form.
    formBuilder:read:form Get a list of available DaVinci forms.
    formBuilder:update:form Update an existing DaVinci form.
    formBuilder:delete:form Delete a DaVinci form.
    formBuilder:read:recaptchaV2Config Read the values for the Site Key and Secret Key fields of all Google reCAPTCHA verifications embedded in any DaVinci forms in a PingOne environment.
    formBuilder:update:recaptchaV2Config Update the values for the Site Key and Secret Key fields of all Google reCAPTCHA verifications embedded in any DaVinci forms in a PingOne environment.
    formBuilder:delete:recaptchaV2Config Delete the values for the Site Key and Secret Key fields of all Google reCAPTCHA verifications embedded in any DaVinci forms in a PingOne environment.
    gateways:create:gateway Create a gateway to connect your on-premise infrastructure to PingOne and authenticate user identities and data stored in an internal or external directory.
    gateways:read:gateway Read the configuration details of all PingOne gateways. Gateways connect your on-premise infrastructure to PingOne.
    gateways:update:gateway Update the settings for a PingOne gateway.
    gateways:delete:gateway Delete a gateway to remove the connection between your on-premise infrastructure and PingOne.
    globalregistry:read:console Access to PingOne administrator console.
    identityProviders:create:identityProvider Create an identity provider (IdP) resource. External IdP connections allow users to authenticate with PingOne using credentials provided by the IdP when configured as part of an authentication policy.
    identityProviders:read:identityProvider Read identity provider (IdP) resources. External IdP connections allow users to authenticate to PingOne using credentials provided by the external IdP.
    identityProviders:update:identityProvider Update an identity provider (IdP) resource to change how users authenticate to PingOne using the credentials provided by the IdP.
    identityProviders:delete:identityProvider Delete an identity provider (IdP) resource. Users will no longer be able to use the external IdP connection to authenticate using credentials provided by the IdP.
    identitycloud:create:orchestration Create an Advanced Identity Cloud orchestration in a specific environment
    identitycloud:update:orchestration Update an Advanced Identity Cloud orchestration in a specific environment
    identitycloud:admin:superadmin Grants the Super Admin role in Advanced Identity Cloud which has full access to all administrative features and can manage every aspect of this tenant, including adding other administrators.
    identitycloud:admin:tenantadmin Grants the Tenant Admin role in Advanced Identity Cloud which has full access to all administrative features, except the ability to add other administrators.
    idverifications:create:document Submit a user-submitted document. User-submitted documents are government issued identity documents, such as a driver license or passport, used for identity verification.
    idverifications:get:document Read user-submitted documents. User-submitted documents are government issued identity documents, such as a driver license or passport, used for identity verification.
    idverifications:update:document Update a user-submitted document. User-submitted documents are government issued identity documents, such as a driver license or passport, used for identity verification.
    idverifications:delete:document Delete a user-submitted document. User-submitted documents are government issued identity documents, such as a driver license or passport, used for identity verification.
    idverifications:create:identityRecordMatching Create Identity Record Matching. Identity Record Matching compares two sets of identity data and returns a score of confidence that the data match.
    idverifications:get:referenceData Read data submitted by a user during a voice verification.
    idverifications:delete:referenceData Delete data submitted by a user during a voice verification.
    idverifications:get:verifiedUserData Read verified user data from a verification transaction.
    idverifications:update:verifiedUserData Update verified user data from a verification transaction.
    idverifications:delete:verifiedUserData Delete verified user data from a verification transaction.
    idverifications:create:verifyPolicy Create a PingOne Verify policy.
    idverifications:read:verifyPolicy Read a PingOne Verify policy.
    idverifications:update:verifyPolicy Update a PingOne Verify policy.
    idverifications:delete:verifyPolicy Delete a PingOne Verify policy.
    idverifications:create:verifyTransactions Create a user verification transaction.
    idverifications:read:verifyTransactions Read a user verification transaction.
    idverifications:update:verifyTransactions Update a user verification transaction.
    idverifications:delete:verifyTransactions Delete a user verification transaction.
    idverifications:create:voicePhrase Create the template that defines the phrase the user speaks during voice verification.
    idverifications:read:voicePhrase Read the template that defines the phrase the user speaks during voice verification.
    idverifications:update:voicePhrase Update the template that defines the phrase the user speaks during voice verification.
    idverifications:delete:voicePhrase Delete the template that defines the phrase the user speaks during voice verification.
    idverifications:create:voicePhraseContent Create the phrase that the user speaks aloud for voice verification.
    idverifications:read:voicePhraseContent Read the phrase that the user speaks aloud for voice verification.
    idverifications:update:voicePhraseContent Update the phrase that the user speaks aloud for voice verification.
    idverifications:delete:voicePhraseContent Delete the phrase that the user speaks aloud for voice verification.
    image:create:image Upload an image to PingOne for an environment. The image can be used by other services within the environment, such as user profile.
    image:read:image View any image that has been uploaded to PingOne for an environment.
    image:delete:image Delete any image that has been uploaded to PingOne for an environment.
    integrations:read:integration Read a list of product integration kits, versions, and items in the application catalog.
    langmgt:create:language Add a language to configure for an environment.
    langmgt:read:language Read a list of languages that are currently configured for an environment.
    langmgt:update:language Enable or disable a language for an environment or set a language as the default.
    langmgt:delete:language Delete a language from an environment.
    ldapGateway:execute:directLdap Allow specific clients, such as PingFederate and the PingOne DaVinci connector, to route LDAP operations through PingOne to your on-premise LDAP directories.
    ldapGateway:validate:kerberos Use Kerberos authentication through an LDAP gateway. Available only if you use Microsoft Active Directory as your LDAP directory.
    ldapGateway:read:user Read LDAP users using the LDAP gateway.
    ldapGateway:validate:userPassword Check a user's password through a PingOne LDAP gateway. LDAP gateways connect PingOne with customer-managed LDAP directories.
    licensing:update:environmentLicense Update environment licenses
    licensing:update:mutableProperties Edit the attributes for a license, including the license name or environment assignment.
    mfa:create:createTestDevice Create an MFA device for testing.
    mfa:authenticate:device Initiate device authentication.
    mfa:read:device Read MFA devices.
    mfa:create:deviceAuthenticationPolicy Create an MFA policy. MFA policies are used to define and configure the authentication methods used in your authentication policy.
    mfa:read:deviceAuthenticationPolicy Read an MFA policy. MFA policies are used to define and configure the authentication methods used in your authentication policy.
    mfa:update:deviceAuthenticationPolicy Modify an existing MFA policyUpdate an MFA policy. MFA policies are used to define and configure the authentication methods used in your authentication policy.
    mfa:delete:deviceAuthenticationPolicy Delete an MFA policy. MFA policies are used to define and configure the authentication methods used in your authentication policy.
    mfa:create:fidoDeviceMetadata Create custom FIDO device metadata.
    mfa:read:fidoDeviceMetadata Read FIDO device metadata.
    mfa:delete:fidoDeviceMetadata Delete custom FIDO device metadata.
    mfa:create:fidoPolicy Create a FIDO policy. FIDO policies define which FIDO devices and authenticators can be used for registration and authentication.
    mfa:read:fidoPolicy Read a FIDO policy. FIDO policies define which FIDO devices and authenticators can be used for registration and authentication.
    mfa:update:fidoPolicy Update a FIDO policy. FIDO policies define which FIDO devices and authenticators can be used for registration and authentication.
    mfa:delete:fidoPolicy Delete a FIDO policy. FIDO policies define which FIDO devices and authenticators can be used for registration and authentication.
    mfa:read:mfaSettings Read MFA settings.
    mfa:update:mfaSettings Update MFA settings.
    mfa:delete:mfaSettings Reset MFA settings.
    mfa:read:oathJob Retrieve an OATH Job
    mfa:create:oathToken Add an OATH token to the environment. After you add the OATH token, you can specify it as an authentication method for a specific user. Relevant only for environments that include PingID.
    mfa:read:oathToken Read an OATH token that has been added to the environment. Relevant only for environments that include PingID.
    mfa:update:oathToken Resync an OATH token that has been added to the environment. Relevant only for environments that include PingID.
    mfa:delete:oathToken Delete an OATH token from the environment. Relevant only for environments that include PingID.
    mfa:create:pairingKey Create a pairing key for an MFA device.
    mfa:read:pairingKey Read pairing keys for MFA devices.
    mfa:delete:pairingKey Delete the pairing key for an MFA device.
    notifications:create:emailDomain Create an email domain. Email domains are used for sending out email notifications to your users.
    notifications:read:emailDomain Read the email domains. Email domains are used for sending out email notifications to your users.
    notifications:update:emailDomain Update an email domain. Email domains are used for sending out email notifications to your users.
    notifications:delete:emailDomain Delete an email domain. Email domains are used for sending out email notifications to your users.
    notifications:create:notification Send an event notification to a user.
    notifications:create:notificationsPolicy Create a notification policy. Notification policies are used to limit the number of SMS/voice or email notifications that can be sent per day.
    notifications:read:notificationsPolicy Read notification policies. Notification policies are used to limit the number of SMS/voice or email notifications that can be sent per day.
    notifications:update:notificationsPolicy Update a notification policy. Notification policies are used to limit the number of SMS/voice or email notifications that can be sent per day.
    notifications:delete:notificationsPolicy Delete a notification policyDelete a notification policy. Notification policies are used to limit the number of SMS/voice or email notifications that can be sent per day.
    notifications:read:notificationsSettings Read fallback order for SMS/Voice providers and 'from' and 'reply to' fields for email notifications.
    notifications:update:notificationsSettings Update fallback order for SMS/Voice providers and reset 'from' and 'reply to' fields for email notifications.
    notifications:delete:notificationsSettings Reset fallback order for SMS/Voice providers and reset 'from' and 'reply to' fields for email notifications.
    notifications:read:quota Read the daily notification quota set in notification policy.
    notifications:read:template Read a notification template. Notification templates are used to inform users about certain events in PingOne.
    notifications:create:templateContent Create content for a notification template. Notification templates are used to inform users about some event types in PingOne.
    notifications:read:templateContent Read the content of a notification template. Notification templates are used to inform users about some event types in PingOne.
    notifications:update:templateContent Update content for a notification template. Notification templates are used to inform users about some event types in PingOne.
    notifications:delete:templateContent Delete the content of a notification template. Notification templates are used to inform users about some event types in PingOne.
    notifications:reset:userQuota Reset notifications quota
    orgmgt:create:deployment Create deployments for other Ping products in the PingOne environment. These other products might require additional configuration outside of PingOne.
    orgmgt:promote:environment Promote an environment from sandbox to production. A sandbox environment is used to test functionality before deploying to production.
    orgmgt:update:environment Update environment properties to add or remove services, change the environment name or description, or update license information. Environments are the primary subdivision of an organization.
    osmosis:check:connection Test the provisioning connection to an external identity provider before saving the configuration.
    osmosis:read:mapping Read the attribute mapping for a provisioning rule. Attribute mapping defines how attributes from an external identity store correspond to attributes in PingOne.
    osmosis:update:mapping Update the attribute mapping for a provisioning rule. Attribute mapping defines how attributes from an external identity store correspond to attributes in PingOne.
    osmosis:delete:mapping Delete an attribute mapping for a provisioning rule. Attribute mapping defines how attributes from an external identity store correspond to attributes in PingOne.
    osmosis:read:plan Read a provisioning plan. A provisioning plan is a list of all the provisioning rules in an environment.
    osmosis:update:plan Update a provisioning plan. A provisioning plan is a list of all the provisioning rules in an environment.
    osmosis:delete:plan Delete a provisioning plan. A provisioning plan is a list of all the provisioning rules in an environment.
    osmosis:create:revision Create a provisioning configuration. A provisioning configuration includes the provisioning connection and provisioning rule.
    osmosis:get:revision Read a provisioning configuration. A provisioning configuration includes the provisioning connection and provisioning rule.
    osmosis:read:rule Read a provisioning rule. A provisioning rule defines which users are provisioned and how attributes are mapped between PingOne and the external identity store.
    osmosis:update:rule Update a provisioning rule. A provisioning rule defines which users are provisioned and how attributes are mapped between PingOne and the external identity store.
    osmosis:delete:rule Delete a provisioning rule. A provisioning rule defines which users are provisioned and how attributes are mapped between PingOne and the external identity store.
    osmosis:read:store Read a provisioning connection. A provisioning connection includes authorization information for the connection type and configuration options, such as provisioning and deprovisioning actions.
    osmosis:update:store Update a provisioning connection. A provisioning connection includes authorization information for the connection type and configuration options, such as provisioning and deprovisioning actions.
    osmosis:delete:store Delete a provisioning connection. A provisioning connection includes authorization information for the connection type and configuration options, such as provisioning and deprovisioning actions.
    p14e:admin:application Used only for SSO to PingOne for Enterprise. Enables Application Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:auditReport Used only for SSO to PingOne for Enterprise. Enables Audit & Report Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:device Used only for SSO to PingOne for Enterprise. Enables PingID Device Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:global Used only for SSO to PingOne for Enterprise. Enables Global Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:identityRepository Used only for SSO to PingOne for Enterprise. Enables Identity Repository Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:saas Used only for SSO to PingOne for Enterprise. Enables SaaS Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:serviceUser Used only for SSO to PingOne for Enterprise. Enables Service User Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:support Used only for SSO to PingOne for Enterprise. Enables Global Administrator role with read-only access for the PingOne admin in PingOne for Enterprise. For write access, you must also add the PingOne for Enterprise Editing Access permission.
    p14e:admin:update Use with a PingOne for Enterprise role permission. Enables write access for the PingOne admin in PingOne for Enterprise.
    permissions:read:applicationRoleAssignments Read admin roles that are assigned to an application scope, including the role permissions. Roles are used by worker applications only.
    permissions:read:gatewayRoleAssignments Read the list of roles and the associated permissions associated with a gateway scope. The gateway scope defines the attributes that can be accessed in the external LDAP directory.
    permissions:read:groupRoleAssignments Read the admin roles that are assigned to a group.
    permissions:read:userRoleAssignments Read admin roles that are assigned to a user, including the role permissions.
    pingenterprise:create:orchestration Creates a Orchestration flow for Ping Enterprise deployment
    pingenterprise:read:orchestration Retrieve Orchestration flow for Ping Enterprise deployment
    pingenterprise:update:orchestration Updates Orchestration flow for Ping Enterprise deployment
    pingenterprise:delete:orchestration Deletes Orchestration flow for Ping Enterprise deployment
    pingfederate:admin:auditor Used only for SSO to PingFederate. Enables the PingFederate Auditor role for the PingOne admin in PingFederate.
    pingfederate:admin:crypto Used only for SSO to PingFederate. Enables the PingFederate Crypto Administrator role for the PingOne admin in PingFederate.
    pingfederate:admin:expressions Used only for SSO to PingFederate. Enables the PingFederate Expressions Administrator role for the PingOne admin in PingFederate.
    pingfederate:admin:system Used only for SSO to PingFederate. Enables the PingFederate Administrator role for the PingOne admin in PingFederate.
    pingfederate:admin:users Used only for SSO to PingFederate. Enables the PingFederate Users Administrator role for the PingOne admin in PingFederate.
    pingid:read:activity Read PingID user last activity
    pingid:read:integration Read PingID user integrations(services)
    pingid:update:integration Update PingID user integration(service)
    pingid:execute:migration Start an integration of PingID with PingOne.
    pingid:read:migration Check the status of the integration of PingID with PingOne.
    pingid:validate:migration Validate resources such as PingID authentication policies before integrating PingID with PingOne.
    pingintelligence:create:orchestration Creates a Orchestration flow for Ping Intelligence deployment
    pingintelligence:read:orchestration Retrieve Orchestration flow for Ping Intelligence deployment
    pingintelligence:update:orchestration Updates Orchestration flow for Ping Intelligence deployment
    pingintelligence:delete:orchestration Deletes Orchestration flow for Ping Intelligence deployment
    prediction:create:prediction Create a prediction
    provisioning:get:connectionSensitiveConfiguration Read the authentication details, which can include sensitive information, for a provisioning configuration. A provisioning configuration includes the provisioning connection and provisioning rule.
    provisioning:create:provisioningSyncOrchestration Create a provisioning sync orchestration for an environment. Sync orchestration is required by the PingOne gateway to provision users inbound into PingOne.
    provisioning:update:provisioningSyncOrchestration Update a provisioning sync orchestration to allow a gateway to provision users to a PingOne environment. Sync orchestration is required by the PingOne gateway to provision users inbound into PingOne.
    radiusGateway:read:session Read radius session details for audit purposes
    resources:create:attribute Create an attribute for a custom resource. Custom resource attributes are mapped as claims in access tokens to convey additional information about their use to applications.
    resources:read:attribute Read a list of custom attributes for a resource. Custom resource attributes are mapped as claims in access tokens to convey additional information about their use to applications.
    resources:update:attribute Update an attribute for a custom resource. Custom resource attributes are mapped as claims in access tokens to convey additional information about their use to applications.
    resources:delete:attribute Delete a custom attribute from a resource. Custom resource attributes are mapped as claims in access tokens to convey additional information about their use to applications.
    resources:create:resource Create a resource. Resources are protected endpoints that applications can access using OAuth 2 authorization services.
    resources:read:resource Read the resources in the environment. Resources are protected endpoints that applications can access using OAuth 2 authorization services.
    resources:update:resource Update the configuration of a resource. Resources are the protected endpoints that applications can access using OAuth 2 authorization services.
    resources:delete:resource Delete a resource. Resources are protected endpoints that applications can access using OAuth 2 authorization services.
    resources:create:scope Create a scope for a resource. Resource scopes can be associated with applications and define application access to user details, such as name and email address.
    resources:read:scope Read the scope for a resource. Resource scopes can be associated with applications and define application access to user details, such as name and email address.
    resources:update:scope Update the scope for a resource. Resource scopes can be associated with applications and define application access to user details, such as name and email address.
    resources:delete:scope Delete a scope from a resource. Resource scopes can be associated with applications and define application access to user details, such as name and email address.
    risk:create:evaluation Create a risk evaluation, which is used to calculate the risk level and other risk-related details associated with an event.
    risk:read:evaluation Read risk evaluation details. Risk evaluations are used to calculate the risk level and other risk-related details associated with an event.
    risk:update:evaluation Update a risk evaluation with the completion status to allow the learning mechanism to improve risk evaluation precision.
    risk:create:feedback Create risk feedback
    risk:create:policy Create a risk policy for use in risk evaluations.
    risk:read:policy Read risk policies, which are used in risk evaluations.
    risk:update:policy Modify an existing risk policy. Risk policies are used in risk evaluations.
    risk:delete:policy Delete a risk policy. Risk policies are used in risk evaluations.
    risk:create:predictor Create a risk predictor for use in risk policies.
    risk:read:predictor Read risk predictors, which are used in risk policies.
    risk:update:predictor Modify an existing risk predictor for use in risk policies.
    risk:delete:predictor Delete a risk predictor. Risk predictors are used in risk policies.
    riskDetection:create:evaluation Create detection evaluations for risk service
    scim:read:schema Read the schema for the environment, including its attributes, using the SCIM API. A schema defines the user attributes in the environment.
    scim:create:user Create a user in the environment using the SCIM API.
    scim:read:user Read a list of users in the environment using the SCIM API.
    scim:update:user Update a user account, including name, email address, and other attributes, using the SCIM API.
    scim:delete:user Delete a user from the environment using the SCIM API.
    solutions:create:config Create new or reset an existing configuration for the customer or workforce Getting Started experience to assign default flows for registration, authentication, profile management, and account recovery.
    solutions:read:config Read the configuration data for the CIAM or workforce Getting Started experiences, such as the flows used for registration, authentication, profile management, and account recovery.
    solutions:update:config Update the configuration of the customer or workforce Getting Started experience to use different flows for registration, authentication, profile management, or account recovery.
    solutions:read:flow Read the list of flows available as part of the getting started experience in the admin console.
    solutions:read:token Retrieve a DaVinci access token.
    subscriptions:create:subscription Create a webhook to send event information to an external monitoring system.
    subscriptions:read:subscription Read webhook information. Webhooks are used to subscribe to events of interest in PingOne and push the event information to an external monitoring system.
    subscriptions:update:subscription Update the properties or filters for a webhook to change the information that is sent to your external monitoring system.
    subscriptions:delete:subscription Delete a webhook to stop sending event information to your external monitoring system.
    visualization:read:authentication View the Authentication dashboard. The Authentication dashboard shows a summary of sign-on activity through PingOne and additional authentication metrics for the environment.
    visualization:read:dashboard See dashboards
    visualization:create:exploration Create a data exploration object for use with dashboards and report generation.
    visualization:read:exploration Read the data for a data exploration object. Data exploration objects are used with dashboards and report generation.
    visualization:read:template Read data exploration template
    visualization:read:userDemographics Read the User Demographics dashboard and user demographic data. User demographic data provides information on the distribution of users by population and operating system and browser usage by service.

    Audit Reporting Events

    To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

    Event Type Event Name
    ACCOUNT.LINKED Account Linked
    ACCOUNT.UNLINKED Account Unlinked
    ACTION.CREATED Action Created
    ACTION.DELETED Action Deleted
    ACTION.UPDATED Action Updated
    ADVANCEDSERVICES_ORCHESTRATION.CREATION_COMPLETED Advanced Services Deployment Complete
    ADVANCEDSERVICES_ORCHESTRATION.CREATION_FAILED Advanced Services Deployment Failed
    ADVANCEDSERVICES_ORCHESTRATION.CREATION_START_FAILED Advanced Services Deployment Start Failed
    ADVANCEDSERVICES_ORCHESTRATION.CREATION_STARTED Advanced Services Deployment Started
    ADVANCEDSERVICES_ORCHESTRATION.DELETION_COMPLETED Advanced Services Deprovision Complete
    ADVANCEDSERVICES_ORCHESTRATION.DELETION_FAILED Advanced Services Deprovision Failed
    ADVANCEDSERVICES_ORCHESTRATION.DELETION_START_FAILED Advanced Services Deprovision Start Failed
    ADVANCEDSERVICES_ORCHESTRATION.DELETION_STARTED Advanced Services Deprovision Started
    AGREEMENT_CONSENT.ACCEPTED Agreement Consent Accepted
    AGREEMENT_CONSENT.REVOKED Agreement Consent Revoked
    AGREEMENT_LANGUAGE_REVISION.CREATED Agreement Language Revision Created
    AGREEMENT_LANGUAGE_REVISION.DELETED Agreement Language Revision Deleted
    AGREEMENT_LANGUAGE_REVISION.UPDATED Agreement Language Revision Updated
    AGREEMENT_LANGUAGE.CREATED Agreement Language Created
    AGREEMENT_LANGUAGE.DELETED Agreement Language Deleted
    AGREEMENT_LANGUAGE.UPDATED Agreement Language Updated
    AGREEMENT.CREATED Agreement Created
    AGREEMENT.DELETED Agreement Deleted
    AGREEMENT.UPDATED Agreement Updated
    API_ACCESS_LOG_ENTRY.HTTP_REQUEST_POLICY_EVALUATED HTTP Request Policy Evaluated
    API_ACCESS_LOG_ENTRY.HTTP_RESPONSE_POLICY_EVALUATED HTTP Response Policy Evaluated
    API_SERVER.CREATED API Service Created
    API_SERVER.DELETED API Service Deleted
    API_SERVER.POLICIES_DEPLOYED API Service Deployed
    API_SERVER.UPDATED API Service Updated
    APPLICATION.CREATED Application Created
    APPLICATION.DELETED Application Deleted
    APPLICATION.PLAY_INTEGRITY_MISCONFIGURATION Google Play Services Device Integrity Misconfiguration
    APPLICATION.UPDATED Application Updated
    ASSERTION.CHECK_FAILED Assertion Check Failed
    ASSERTION.CHECK_SUCCESS Assertion Check Success
    AUTHENTICATION_CODE.CREATED Authentication Code Created
    AUTHENTICATION_CODE.DELETED Authentication Code Deleted
    AUTHENTICATION_CODE.UPDATED Authentication Code Updated
    AUTHENTICATION.CREATED Authentication Created
    AUTHENTICATION.UPDATED Authentication Updated
    AUTHORIZE_ATTRIBUTE.CREATED Authorize Attribute Created
    AUTHORIZE_ATTRIBUTE.DELETED Authorize Attribute Deleted
    AUTHORIZE_ATTRIBUTE.UPDATED Authorize Attribute Updated
    AUTHORIZE_CONDITION.CREATED Authorize Condition Created
    AUTHORIZE_CONDITION.DELETED Authorize Condition Deleted
    AUTHORIZE_CONDITION.UPDATED Authorize Condition Updated
    AUTHORIZE_POLICY.CREATED Authorize Policy Created
    AUTHORIZE_POLICY.DELETED Authorize Policy Deleted
    AUTHORIZE_POLICY.UPDATED Authorize Policy Updated
    AUTHORIZE_PROCESSOR.CREATED Authorize Processor Created
    AUTHORIZE_PROCESSOR.DELETED Authorize Processor Deleted
    AUTHORIZE_PROCESSOR.UPDATED Authorize Processor Updated
    AUTHORIZE_SERVICE.CREATED Authorize Service Created
    AUTHORIZE_SERVICE.DELETED Authorize Service Deleted
    AUTHORIZE_SERVICE.UPDATED Authorize Service Updated
    AUTHORIZE_SHARED_ADVICE.CREATED Authorize shared Advice Created
    AUTHORIZE_SHARED_ADVICE.DELETED Authorize shared Advice Deleted
    AUTHORIZE_SHARED_ADVICE.UPDATED Authorize shared Advice Updated
    AUTHORIZE_SHARED_RULE.CREATED Authorize shared Rule Created
    AUTHORIZE_SHARED_RULE.DELETED Authorize shared Rule Deleted
    AUTHORIZE_SHARED_RULE.UPDATED Authorize shared Rule Updated
    AUTHORIZE_TAG.DELETED Authorize Tag Deleted
    AUTHORIZE_TAG.UPDATED Authorize Tag Updated
    BRANDING.DELETED Branding Deleted
    BRANDING.UPDATED Branding Updated
    CERTIFICATE.CREATED Certificate Created
    CERTIFICATE.DELETED Certificate Deleted
    CERTIFICATE.READ Certificate Read
    CERTIFICATE.UPDATED Certificate Updated
    CONTENT.CREATED Content Created
    CONTENT.DELETED Content Deleted
    CONTENT.UPDATED Content Updated
    CONTENTS.DELETED Contents Deleted
    CONTENTS.UPDATED Contents Updated
    CREDENTIAL_TYPE.CREATED Credential Type Created
    CREDENTIAL_TYPE.DELETED Credential Type Deleted
    CREDENTIAL_TYPE.UPDATED Credential Type Updated
    CUSTOM_DOMAIN.CREATED Custom Domain Created
    CUSTOM_DOMAIN.DELETED Custom Domain Deleted
    CUSTOM_DOMAIN.UPDATED Custom Domain Updated
    DAVINCI_INTERACTION.CUSTOM_ANALYTICS DaVinci Interaction Custom Analytics
    DAVINCI_INTERACTION.RECEIVE_REQUEST DaVinci Interaction Receive Request
    DAVINCI_INTERACTION.SEND_ERROR_RESPONSE DaVinci Interaction Send Error Response
    DAVINCI_INTERACTION.SEND_RESPONSE DaVinci Interaction Send Response
    DAVINCI_INTERACTION.START_INTERACTION DaVinci Interaction Started
    DECISION_ENDPOINT.CREATED Decision Endpoint Created
    DECISION_ENDPOINT.DECISION_REQUEST_EVALUATED Decision Request Evaluated
    DECISION_ENDPOINT.DELETED Decision Endpoint Deleted
    DECISION_ENDPOINT.UPDATED Decision Endpoint Updated
    DEVICE_AUTHENTICATION_POLICY.CREATED Auth Method Policy Created
    DEVICE_AUTHENTICATION_POLICY.DELETED Auth Method Policy Deleted
    DEVICE_AUTHENTICATION_POLICY.UPDATED Auth Method Policy Updated
    DEVICE_PAYLOAD.CHECK_INVALID Device Payload Check Invalid
    DEVICE_PAYLOAD.CHECK_SUCCESS Device Payload Check Success
    DEVICE.ACTIVATED Device Activated
    DEVICE.ACTIVATION_FAILED Device Activation Failed
    DEVICE.ACTIVATION_OTP_FAILED Pairing Otp Failed
    DEVICE.ACTIVATION_OTP_INVALID Pairing Otp Invalid
    DEVICE.BLOCKED Device Blocked
    DEVICE.CREATED Device Created
    DEVICE.DELETED Device Deleted
    DEVICE.FRAUD_REPORTED Fraud Reported
    DEVICE.KEY_ROTATION_FAILED Device Key Rotation Failed
    DEVICE.KEY_ROTATION_SUCCEEDED Device Key Rotation Succeeded
    DEVICE.LOCKED Device Locked
    DEVICE.LOGS_RECEIVED Device Mobile Logs Received
    DEVICE.NICKNAME_UPDATED Device Nickname Updated
    DEVICE.PAIRING_FAILED_COMPROMISED Pairing Mobile Device Failed
    DEVICE.UNBLOCKED Device Unblocked
    DEVICE.UNLOCKED Device Unlocked
    DEVICE.UPDATED Device Updated
    DEVICES.ORDER_CREATED Devices Order Created
    DEVICES.ORDER_DELETED Devices Order Deleted
    DEVICES.ORDER_UPDATED Devices Order Updated
    DIGITAL_WALLET_APPLICATION.CREATED Digital Wallet Application Created
    DIGITAL_WALLET_APPLICATION.DELETED Digital Wallet Application Deleted
    DIGITAL_WALLET_APPLICATION.UPDATED Digital Wallet Application Updated
    DIGITAL_WALLET.ACTIVE Digital Wallet Active
    DIGITAL_WALLET.DELETED Digital Wallet Deleted
    DIGITAL_WALLET.DISABLED Digital Wallet Disabled
    DIGITAL_WALLET.EXPIRED Digital Wallet Expired
    DIGITAL_WALLET.PAIRING_REQUIRED Digital Wallet Pairing Required
    DIGITAL_WALLET.UPDATED Digital Wallet Updated
    EARLY_ACCESS_FEATURE.OPT_IN Opted in to early access feature
    EARLY_ACCESS_FEATURE.OPT_OUT Opted out of early access feature
    EMAIL_DOMAIN.CREATED Email Domain Created
    EMAIL_DOMAIN.DELETED Email Domain Deleted
    ENVIRONMENT.CAPABILITIES Environment Capabilities
    ENVIRONMENT.CREATED Environment Created
    ENVIRONMENT.DELETED Environment Deleted
    ENVIRONMENT.DEMOTED Environment Demoted
    ENVIRONMENT.PROMOTED Environment Promoted
    ENVIRONMENT.UPDATED Environment Updated
    EXECUTION.SKIPPED Job Execution Skipped
    EXECUTION.TIMED_OUT Job Execution Timed Out
    FIDO_METADATA.CREATED FIDO Custom authenticator Created
    FIDO_METADATA.DELETED FIDO Custom authenticator Deleted
    FIDO_POLICY.CREATED FIDO Policy Created
    FIDO_POLICY.DELETED FIDO Policy Deleted
    FIDO_POLICY.UPDATED FIDO Policy Updated
    FLOW_DEFINITION.CREATED Flow Definition Created
    FLOW_DEFINITION.DELETED Flow Definition Deleted
    FLOW_DEFINITION.UPDATED Flow Definition Updated
    FLOW_EXECUTION.CREATED Flow Execution Created
    FLOW_EXECUTION.UPDATED Flow Execution Updated
    FLOW.CREATED Flow Started
    FLOW.DELETED Flow Completed
    FLOW.UPDATED Flow Updated
    GATEWAY_INSTANCE.CREATED Gateway Instance Created
    GATEWAY_INSTANCE.DELETED Gateway Instance Deleted
    GATEWAY_INSTANCE.UPDATED Gateway Instance Updated
    GATEWAY.CREATED Gateway Created
    GATEWAY.DELETED Gateway Deleted
    GATEWAY.UPDATED Gateway Updated
    GRANT.CREATED Grant Created
    GRANT.DELETED Grant Deleted
    GRANT.UPDATED Grant Updated
    GROUP.CREATED Group Created
    GROUP.DELETED Group Deleted
    GROUP.UPDATED Group Updated
    IDENTITY_PROVIDER.CREATED Identity Provider Created
    IDENTITY_PROVIDER.DELETED Identity Provider Deleted
    IDENTITY_PROVIDER.UPDATED Identity Provider Updated
    IDP_ATTRIBUTE.CREATED Idp Attribute Created
    IDP_ATTRIBUTE.DELETED Idp Attribute Deleted
    IDP_ATTRIBUTE.UPDATED Idp Attribute Updated
    IMAGE.ACTIVATED Image Activated
    IMAGE.CREATED Image Created
    IMAGE.DELETED Image Deleted
    INSTANT_MESSAGING_DELIVERY_SETTINGS.CREATED Instant Messaging Delivery Settings Created
    INSTANT_MESSAGING_DELIVERY_SETTINGS.DELETED Instant Messaging Delivery Settings Deleted
    INSTANT_MESSAGING_DELIVERY_SETTINGS.UPDATED Instant Messaging Delivery Settings Updated
    IP_RATE_LIMIT_THRESHOLD.EXCEEDED IP Rate Limit Threshold Exceeded
    IP_RATE_LIMIT.EXCEEDED IP Rate Limit Exceeded
    ISSUANCE_RULE.CREATED Issuance Rule Created
    ISSUANCE_RULE.DELETED Issuance Rule Deleted
    ISSUANCE_RULE.UPDATED Issuance Rule Updated
    ISSUANCE.CREATED Issuance Created
    KEY.CREATED Key Created
    KEY.DELETED Key Deleted
    KEY.READ Key Read
    KEY.UPDATED Key Updated
    KRP.CREATED Key Rotation Policy Created
    KRP.DELETED Key Rotation Policy Deleted
    KRP.ROTATED Key Rotation Policy Rotated
    KRP.UPDATED Key Rotation Policy Updated
    LICENSE_RATE_LIMIT_THRESHOLD.EXCEEDED License Rate Limit Threshold Exceeded
    LICENSE_RATE_LIMIT.EXCEEDED License Rate Limit Exceeded
    LICENSE.CREATED License Created
    LICENSE.DELETED License Deleted
    LICENSE.UPDATED License Updated
    MEMBER_OF_GROUP.CREATED Member of Group Created
    MEMBER_OF_GROUP.DELETED Member of Group Deleted
    MFA_SETTINGS.UPDATED MFA Settings Updated
    NOTIFICATION_POLICY.CREATED Notification Policy Created
    NOTIFICATION_POLICY.DELETED Notification Policy Deleted
    NOTIFICATION_POLICY.UPDATED Notification Policy Updated
    NOTIFICATION.CREATED Notification Created
    NOTIFICATION.REJECTED Notification Rejected
    NOTIFICATION.UPDATED Notification Updated
    NOTIFICATIONS_SETTINGS.UPDATED Notification Settings Updated
    OATH_TOKEN.CREATED Oath Token Created
    OATH_TOKEN.RESYNC_INVALID_OTP Oath Token Resync Failed (Invalid Passcode)
    OATH_TOKEN.RESYNC_MAX_ATTEMPTS Oath Token Resync Failed (Max Resync Attempts Exceeded)
    OATH_TOKEN.RESYNC_SUCCESS Oath Token Resync Success
    OATH_TOKEN.RESYNC_USER_NOT_PAIRED Oath Token Resync Failed (User Not Paired with Token)
    OATH_TOKEN.REVOKED Oath Token Revoked
    OATH_TOKENS_BULK.CREATED Oath Tokens Imported
    OATH_TOKENS_BULK.REVOKED Oath Tokens Revoked
    OAUTH_CONSENT.ACCEPTED OAuth Consent Accepted
    OAUTH_CONSENT.DECLINED OAuth Consent Declined
    OAUTH_CONSENT.REVOKED OAuth Consent Revoked
    ORGANIZATION.CAPABILITIES Organization Capabilities
    ORGANIZATION.CREATED Organization Created
    ORGANIZATION.DELETED Organization Deleted
    ORGANIZATION.UPDATED Organization Updated
    OTP.CHECK_FAILED Otp Check Failed
    OTP.CHECK_INVALID Otp Check Invalid
    OTP.CHECK_SUCCESS Otp Check Success
    PASSWORD.CHECK_FAILED Password Check Failed
    PASSWORD.CHECK_SUCCEEDED Password Check Succeeded
    PASSWORD.EXTERNAL_SET Password External Set
    PASSWORD.FORCE_CHANGE Password Force Change
    PASSWORD.RECOVERY Password Recovery
    PASSWORD.RESET Password Reset
    PASSWORD.SET Password Set
    PASSWORD.UNLOCKED Password Unlocked
    PASSWORD.UNSET Password Unset
    PHONE_DELIVERY_SETTINGS.CREATED Phone Delivery Settings Created
    PHONE_DELIVERY_SETTINGS.DELETED Phone Delivery Settings Deleted
    PHONE_DELIVERY_SETTINGS.UPDATED Phone Delivery Settings Updated
    POLICY.CREATED Password Policy Created
    POLICY.DELETED Password Policy Deleted
    POLICY.UPDATED Password Policy Updated
    POPULATION.CREATED Population Created
    POPULATION.DELETED Population Deleted
    POPULATION.UPDATED Population Updated
    PREVIOUS_SECRET.REVOKED Previous Secret Revoked
    PREVIOUS_SECRET.USED Previous Secret Used
    PROVISION_CREDENTIAL.ACCEPTED Provisioned Credential Accepted
    PROVISION_CREDENTIAL.CREATED Provisioned Credential Created
    PROVISION_CREDENTIAL.DELETED_FROM_WALLET Provisioned Credential Deleted From Wallet
    PROVISION_CREDENTIAL.DELETED Provisioned Credential Deleted
    PROVISION_CREDENTIAL.REJECTED Provisioned Credential Rejected
    PROVISION_CREDENTIAL.REVOKED Provisioned Credential Revoked
    PROVISIONING_CONNECTION.CREATED Provisioning Identity Connection Created
    PROVISIONING_CONNECTION.DELETED Provisioning Identity Connection Deleted
    PROVISIONING_CONNECTION.UPDATED Provisioning Identity Connection Updated
    PROVISIONING_GROUP_MEMBERSHIP_SYNC.FAILURE Provisioning Group Membership Sync Failure
    PROVISIONING_GROUP_SYNC.FAILURE Provisioning Group Sync Failure
    PROVISIONING_IDENTITY_SYNC.FAILURE Provisioning Identity Sync Failure
    PROVISIONING_MAPPING.CREATED Provisioning Mapping Created
    PROVISIONING_MAPPING.DELETED Provisioning Mapping Deleted
    PROVISIONING_MAPPING.UPDATED Provisioning Mapping Updated
    PROVISIONING_POLL.FAILURE Provisioning Poll Failure
    PROVISIONING_RULE.CREATED Provisioning Rule Created
    PROVISIONING_RULE.DELETED Provisioning Rule Deleted
    PROVISIONING_RULE.UPDATED Provisioning Rule Updated
    PROVISIONING_SYNC.FAILURE Provisioning Sync Failure
    PROVISIONING_SYNC.STARTED Provisioning Sync Started
    PUSH_CREDENTIALS.CREATED Push Credentials Created
    PUSH_CREDENTIALS.DELETED Push Credentials Deleted
    PUSH_CREDENTIALS.UPDATED Push Credentials Updated
    RADIUS_SESSION.CREATED RADIUS Session Created
    RADIUS_SESSION.UPDATED RADIUS Session Updated
    RESCUE_IDENTITY.CREATED Rescue Identity Created
    RESOURCE_ATTRIBUTE.CREATED Resource Attribute Created
    RESOURCE_ATTRIBUTE.DELETED Resource Attribute Deleted
    RESOURCE_ATTRIBUTE.UPDATED Resource Attribute Updated
    RESOURCE.CREATED Resource Created
    RESOURCE.DELETED Resource Deleted
    RESOURCE.UPDATED Resource Updated
    RISK_EVALUATION.CREATED Risk Evaluation Created
    RISK_EVALUATION.STAGING_CREATED Risk Staging Evaluation Created
    RISK_EVALUATION.UPDATED Risk Evaluation Updated
    RISK_FEEDBACK.CREATED Risk Feedback Created
    RISK_POLICY_SET.CREATED Risk Policy Created
    RISK_POLICY_SET.DELETED Risk Policy Deleted
    RISK_POLICY_SET.ORDER_UPDATED Risk Policy Order Updated
    RISK_POLICY_SET.UPDATED Risk Policy Updated
    RISK_PREDICTOR.CREATED Risk Predictor Created
    RISK_PREDICTOR.DELETED Risk Predictor Deleted
    RISK_PREDICTOR.UPDATED Risk Predictor Updated
    ROLE_ASSIGNMENT.CREATED Role Assignment Created
    ROLE_ASSIGNMENT.DELETED Role Assignment Deleted
    ROLE.CREATED Role Created
    ROLE.DELETED Role Deleted
    ROLE.UPDATED Role Updated
    SAML_ATTRIBUTE.CREATED SAML Attribute Created
    SAML_ATTRIBUTE.DELETED SAML Attribute Deleted
    SAML_ATTRIBUTE.UPDATED SAML Attribute Updated
    SCHEDULE.SKIPPED Schedule Skipped
    SCHEMA_ATTRIBUTE.CREATED Schema Attribute Created
    SCHEMA_ATTRIBUTE.DELETED Schema Attribute Deleted
    SCHEMA_ATTRIBUTE.UPDATED Schema Attribute Updated
    SCOPE.CREATED Scope Created
    SCOPE.DELETED Scope Deleted
    SCOPE.UPDATED Scope Updated
    SECRET.READ Secret Read
    SECRET.UPDATED Secret Updated
    SESSION.CREATED Session Created
    SESSION.DELETED Session Deleted
    SESSION.UPDATED Session Updated
    SETTINGS.UPDATED Settings Updated
    SIGN_ON_POLICY_ASSIGNMENT.CREATED Sign On Policy Assignment Created
    SIGN_ON_POLICY_ASSIGNMENT.DELETED Sign On Policy Assignment Deleted
    SIGN_ON_POLICY_ASSIGNMENT.UPDATED Sign On Policy Assignment Updated
    STAGED_CHANGE.COMPLETED Staged Change Completed
    STAGED_CHANGE.CREATED Staged Change Created
    STAGED_CHANGE.DELETED Staged Change Deleted
    STAGED_CHANGE.FAILED Staged Change Failed
    STAGED_CHANGE.UPDATED Staged Change Updated
    SUBSCRIPTION.CREATED Subscription Created
    SUBSCRIPTION.DELETED Subscription Deleted
    SUBSCRIPTION.UPDATED Subscription Updated
    THEME.CREATED Theme Created
    THEME.DELETED Theme Deleted
    THEME.UPDATED Theme Updated
    TRUSTED_EMAIL.ACTIVE Trusted Email Activated
    TRUSTED_EMAIL.CREATED Trusted Email Created
    TRUSTED_EMAIL.DELETED Trusted Email Deleted
    TRUSTED_EMAIL.SEND_CODE Trusted Email Send Code
    USER_CREDENTIAL.DELETED User Credential Deleted
    USER_CREDENTIAL.ISSUED User Credential Issued
    USER_CREDENTIAL.PENDING User Credential Pending
    USER_CREDENTIAL.REVOKED User Credential Revoked
    USER_CREDENTIAL.UPDATED User Credential Updated
    USER.ACCESS_ALLOWED User Access Allowed
    USER.ACCESS_DENIED User Access Denied
    USER.CREATED User Created
    USER.DELETED User Deleted
    USER.INVITE_ACCEPTED User Invite Accepted
    USER.INVITE_REVOKED User Invite Revoked
    USER.INVITE_UPDATED User Invite Updated
    USER.INVITED User Invited
    USER.KERBEROS_FAILED Kerberos Check Failed
    USER.KERBEROS_SUCCEEDED Kerberos Check Succeeded
    USER.LOCKED User Locked
    USER.MOVED User Moved
    USER.QUOTA_RESET User Quota Reset
    USER.REINVITED User Re-Invited
    USER.SLO_FAILURE User Slo Failure
    USER.SLO_PARTIAL_LOGOUT User Slo Partial Logout
    USER.SLO_REQUESTED User Slo Requested
    USER.SLO_SUCCESS User Slo Success
    USER.UNLOCKED User Unlocked
    USER.UPDATE_ON_AUTH_FAILED Attribute Updates via Gateway Failed
    USER.UPDATE_ON_AUTH_SUCCEEDED Attribute Updates via Gateway Succeeded
    USER.UPDATED User Updated
    VALIDATION_TRANSACTION.CREATED Validation Transaction Created
    VALIDATION_TRANSACTION.DELETED Validation Transaction Deleted
    VALIDATION_TRANSACTION.UPDATED Validation Transaction Updated
    VERIFY_APPEVENT.CREATED Verify App Event Created
    VERIFY_METADATA.CREATED Verify Metadata Created
    VERIFY_METADATA.DELETED Verify Metadata Deleted
    VERIFY_POLICY.CREATED Verify Policy Created
    VERIFY_POLICY.DELETED Verify Policy Deleted
    VERIFY_POLICY.UPDATED Verify Policy Updated