PingOne Platform APIs

Experiences

The Experiences service enables you to configure user sign-on experiences for particular user audiences. You can create, read, update and delete an experience.

Experiences data model

Property Type Required Mutable Description

id

String

N/A

Read-only

The resource’s unique identifier.

createdAt

String

N/A

Read-only

The timestamp when the resource was created.

updatedAt

String

N/A

Read-only

The timestamp when the resource was last updated.

davinciFlowId

String

N/A

Read-only

The identifier for the Davinci flow associated with the experience.

name

String

Required

Mutable

A name unique to the environment to assign to the experience.

description

String

Optional

Mutable

A description of the experience.

flowType

String

Optional

Mutable

Flow types categorize the user interaction. Accepted values are: USERNAME_AND_PASSWORD, IDENTIFIER_FIRST, IDENTITY_PROVIDER_FIRST.

firstFactor

Object

Required

Mutable

Only available when flowType is IDENTIFIER_FIRST. Contains the authentication configuration.

firstFactor.passwordless

Object

Optional

Mutable

Only available when flowType is IDENTIFIER_FIRST. Contains the configuration for Passwordless authentication.

firstFactor.passwordless.enabled

Boolean

Required

Mutable

Only available when flowType is IDENTIFIER_FIRST. Enables or disables Passwordless authentication. Defaults to false.

firstFactor.passwordless.usernameFirst

Boolean

Required/Optional

Mutable

Only available when flowType is IDENTIFIER_FIRST. Required when firstFactor.passwordless.enabled is true. Enables or disables Passkey, SMS, or One-Time Password (OTP)-based passwordless flow. Defaults to false.

firstFactor.passwordless.passkeyPolicies

Array

Required

Mutable

Only available when flowType is IDENTIFIER_FIRST. Currently, only a single FIDO2 policy can be specified. An array is used to enable multi-policy selection in the future.

firstFactor.passwordless.passkeyPolicies.id

String

Required/Optional

Mutable

Only available when flowType is IDENTIFIER_FIRST. Required when firstFactor.passwordless.passkeyPolicies is specified. A Fido2 policy ID.

firstFactor.passwordless.passkeyPolicies.type

String

Required/Optional

Immutable

Only available when flowType is IDENTIFIER_FIRST. Required when firstFactor.passwordless.passkeyPolicies is specified. This value must be STANDARD_MFA.

firstFactor.passkeyOrBioMetric

Object

Required

Mutable

Only available when flowType is IDENTIFIER_FIRST. Contains the configuration for Passkey or Biometric authentication.

firstFactor.passkeyOrBioMetric.enabled

Boolean

Required

Mutable

Only available when flowType is IDENTIFIER_FIRST. Enables or disables Passkey or Biometric authentication. Defaults to false.

firstFactor.passkeyOrBioMetric.passkeyPolicies

Array

Required

Mutable

Only available when flowType is IDENTIFIER_FIRST. Currently, only a single FIDO2 policy can be specified. An array is used to enable multi-policy selection in the future.

firstFactor.passkeyOrBioMetric.passkeyPolicies.id

String

Required/Optional

Mutable

Only available when flowType is IDENTIFIER_FIRST. Required when firstFactor.passkeyOrBioMetric.passkeyPolicies is specified. A Fido2 policy ID.

firstFactor.passkeyOrBioMetric.passkeyPolicies.type

String

Required/Optional

Immutable

Only available when flowType is IDENTIFIER_FIRST. Required when firstFactor.passkeyOrBioMetric.passkeyPolicies is specified. This value must be STANDARD_MFA.

firstFactor.identityProviders

Object

Required

Mutable

Only available when flowType is IDENTITY_PROVIDER_FIRST. Contains the configuration for identity providers.

firstFactor.identityProviders.enabled

Boolean

Required

Mutable

Only available when flowType is IDENTITY_PROVIDER_FIRST. Enables or disables identity provider authentication. Defaults to false.

firstFactor.identityProviders.socialProviders

Array

Required

Mutable

Only available when flowType is IDENTITY_PROVIDER_FIRST. Required when firstFactor.identityProviders.enabled is true. An array of social providers used as IdPs. See Identity Providers.

firstFactor.identityProviders.socialProviders.id

String

Required/Optional

Mutable

Only available when flowType is IDENTITY_PROVIDER_FIRST. Required when firstFactor.identityProviders.socialProviders is specified. An identify provider ID for a social provider.

firstFactor.identityProviders.socialProviders.name

String

Required/Optional

Mutable

Only available when flowType is IDENTITY_PROVIDER_FIRST. Required when firstFactor.identityProviders.socialProviders is specified. A name of a social provider used as an IdP.

firstFactor.identityProviders.socialProviders.type

String

Required/Optional

Immutable

Only available when flowType is IDENTITY_PROVIDER_FIRST. Required when firstFactor.identityProviders.socialProviders is specified. The type of IdP. See Identity Provider Management.

firstFactor.rememberMe

Boolean

Optional

Mutable

Set this to true to remember the specified social providers. Defaults to false.

firstFactor.sessionTimeout

Object

Optional

Mutable

Contains the time unit and value configuration for session timeout.

firstFactor.sessionTimeout.unit

String

Required/Optional

Mutable

Required when firstFactor.sessionTimeout is specified. The unit of time to use for session timeout. This can be one of the following: MM (minutes),HH (hours), DD (days), WW (weeks).

firstFactor.sessionTimeout.value

String

Required/Optional

Mutable

Required when firstFactor.sessionTimeout.unit is specified. The corresponding length of time value for the session timeout.

mfa

Object

Required

Mutable

Contains the configuration for multi-factor authentication.

mfa.enabled

Boolean

Required

Mutable

Enables or disables multi-factor authentication. Defaults to false.

mfa.accessPolicies

Array

Required

Mutable

Required when mfa.enabled is true. Currently, only a single Risk Policy or Device Authentication Policy identifier can be specified. An array is used to enable multi-policy selection in the future.

mfa.accessPolicies.id

String

Required/Optional

Mutable

Required when mfa.enabled is true. This can be either a Risk Policy ID or a Device Authentication Policy ID.

mfa.accessPolicies.type

String

Required/Optional

Immutable

Required when mfa.enabled is true. If mfa.accessPolicies.id is a Risk Policy ID, this must be RISK_MFA. If mfa.accessPolicies.id is a Device Authentication Policy ID, this must be STANDARD_MFA.

mfa.sessionTimeout

Object

Optional

Mutable

Contains the time unit and value configuration for session timeout.

mfa.sessionTimeout.unit

String

Required/Optional

Mutable

Required when mfa.sessionTimeout is specified. The unit of time to use for session timeout. This can be one of the following: MM (minutes),HH (hours), DD (days), WW (weeks).

mfa.sessionTimeout.value

String

Required/Optional

Mutable

Required when mfa.sessionTimeout.unit is specified. The corresponding length of time value for the session timeout.

mfa.enrollment

Object

Required

Mutable

Contains the configuration for multi-factor authentication enrollment.

mfa.enrollment.enabled

Boolean

Required

Mutable

Enables or disables multi-factor authentication enrollment. Defaults to false.

mfa.enrollment.required

Boolean

Required

Mutable

Required when mfa.enrollment.enabled is true. Enables or disables requirement for multi-factor authentication enrollment. Defaults to false.

accountRecovery

Object

Required

Mutable

Contains the configuration for account recovery.

accountRecovery.enabled

Boolean

Required

Mutable

Enables or disables account recovery authentication enrollment. Defaults to false.

accountRecovery.accessPolicies

Object[]

Required

Mutable

Required when accountRecovery.enabled is true. Currently, only a single Risk Policy identifier object can be specified. An array is used to enable multi-policy selection in the future.

accountRecovery.accessPolicies.id

String

Required/Optional

Mutable

Required when accountRecovery.enabled is true. A Risk Policy ID.

accountRecovery.accessPolicies.type

String

Required/Optional

Immutable

Required when accountRecovery.enabled is true. This must be RISK_MFA.

registration

Object

Required

Mutable

Contains the configuration for registration.

registration.enabled

Boolean

Required

Mutable

Enables or disables registration enrollment. Defaults to false.

registration.enrollment

Object

Required

Mutable

Contains the configuration for multi-factor authentication enrollment.

registration.enrollment.enabled

Boolean

Required

Mutable

Enables or disables registration enrollment. Defaults to false.

registration.enrollment.required

Boolean

Required

Mutable

Required when registration.enrollment.enabled is true. Enables or disables requirement for registration enrollment. Defaults to false.

registration.enrollment.policies

Object[]

Required

Mutable

Required when registration.enrollment.enabled is true. Currently, only a single Device Authentication Policy identifier object can be specified. An array is used to enable multi-policy selection in the future.

registration.enrollment.policies.id

String

Required/Optional

Mutable

Required when registration.enrollment.enabled is true. A Device Authentication Policy ID.

registration.enrollment.policies.type

String

Required/Optional

Immutable

Required when registration.enrollment.enabled is true. This must be STANDARD_MFA.

registration.population

Object

Required/Optional

Mutable

Required when registration.enabled is true. Configures the population for registration.

registration.population.id

String

Required/Optional

Mutable

Required when registration.enabled is true. A population ID.

registration.botDetection

Object

Required

Mutable

Contains the configuration for bot detection.

registration.botDetection.enabled

Boolean

Required

Mutable

Enables or disables bot detection. Defaults to false.

registration.botDetection.accessPolicies

Object[]

Required

Mutable

Required when registration.botDetection.enabled is true. Currently, only a single Risk Policy identifier object can be specified. An array is used to enable multi-policy selection in the future.

registration.botDetection.accessPolicies.id

String

Required/Optional

Mutable

Required when registration.botDetection.enabled is true. A Risk Policy ID.

registration.botDetection.accessPolicies.type

String

Required/Optional

Immutable

Required when registration.botDetection.enabled is true. This must be RISK_MFA.

registration.attributeList

Object[]

Required

Mutable

Contains the attributes required for registration.

registration.attributeList.name

String

Optional

Mutable

The name of a PingOne Standard attribute.

registration.attributeList.required

Boolean

Required

Mutable

Indicates whether the name attribute specified is required.

registration.requireAccountVerification

Boolean

Required

Mutable

Indicates whether account verification is required.

registration.termsOfService

Object

Required

Mutable

Contains the Terms of Service Agreement configuration.

registration.termsOfService.enabled

Boolean

Required

Mutable

Enables or disables the Terms of Service Agreement configuration.

registration.termsOfService.agreementPolicy

Object

Required

Mutable

Required when registration.termsOfService.enabled is true. Contains the Agreement Policy configuration.

registration.termsOfService.agreementPolicy.id

String

Required/Optional

Mutable

Required when registration.termsOfService.enabled is true. An Agreement Policy ID.

theme

Object

Required

Mutable

Contains the Theme configuration.

theme.id

String

Required

Mutable

A Theme ID.

Experiences errors

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

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

400

INVALID_DATA

EMPTY_VALUE or OUT_OF_RANGE or INVALID_VALUE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [name must not be null], Validation Error : [firstFactor.rememberMe Remember me is required and must not be null], or Validation Error : [name size must be between 1 and 255])

When and details

When: A POST /experiences or PUT /experiences/{experienceId} request body fails constraint validation — for example, the request omits name, flowType, firstFactor, mfa, accountRecovery, registration, or theme, omits firstFactor.rememberMe, or supplies a name longer than 255 characters

Details: Per violated constraint: detail EMPTY_VALUE for NotNull constraints, OUT_OF_RANGE for Size constraints, INVALID_VALUE otherwise, target = the field path, message = the constraint message.

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST /experiences or PUT /experiences/{experienceId} request body cannot be deserialized — for example, flowType is not USERNAME_AND_PASSWORD, IDENTIFIER_FIRST, or IDENTITY_PROVIDER_FIRST, or a sessionTimeout.unit value is not MM, HH, DD, or WW

Details: Detail INVALID_VALUE with target = the field path (for example, flowType)

400

INVALID_REQUEST

INVALID_REQUEST

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST /experiences or PUT /experiences/{experienceId} request, or a GET /experiences request with the limit parameter, violates an experience rule: limit is below 1 or above 100, theme.id is not a UUID, mfa.accessPolicies.type is not STANDARD_MFA or RISK_MFA, the environment already has the maximum number of experiences, or a conditional requirement is violated (for example, firstFactor.passwordless.enabled is true when flowType is not IDENTIFIER_FIRST, mfa.accessPolicies is empty when mfa.enabled is true, or registration.population.id is omitted when registration.enabled is true)

Details: Detail INVALID_REQUEST with the rule-violation message and target = the property: pagination limit must be between 1 and 100 for target limit, themeId must be valid UUID for target themeId (a well‑formed UUID that matches no theme returns Invalid themeId=<themeId> for environmentId=<environmentId> with target branding), mfa.accessPolicies type must be either STANDARD_MFA or RISK_MFA for target mfa.accessPolicies.type, Found <count> experiences in an environment <environmentId>. Environment cannot have more than <max> experiences for target experiences count, or the conditional-requirement message for the failing property.

400

INVALID_REQUEST

None

Message: Experience with name=<name> already exists, Invalid experience name=<name>, or Flow type value: <requested> is different from existing flow type: <existing>

When and details

When: A POST /experiences or PUT /experiences/{experienceId} request supplies a name that already exists in the environment, supplies a name with characters other than letters, numbers, spaces, underscores, and hyphens, or a PUT request changes the experience’s flowType

Details: None.

400

INVALID_REQUEST

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A path identifier cannot be parsed as a UUID, or the limit parameter is not a number

Details: None. The response carries the INVALID_REQUEST code with the INVALID_DATA default message.

401

ACCESS_FAILED

ACCESS_FAILED

Message: Access to Experience Builder is not allowed (feature flag) or Access to Experience Builder is not allowed due to terminated license

When and details

When: The Experience Builder feature flag is not enabled for the environment, or the environment’s license status is TERMINATED (applies to all operations)

Details: Detail ACCESS_FAILED with target experience and the gate message.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the experiences:create:experience permission (POST), the experiences:read:experience permission (GET operations), the experiences:update:experience permission (PUT), or the experiences:delete:experience permission (DELETE)

Details: None.

404

NOT_FOUND

None

Message: experience with id=<experienceId> not found in an environment with id=<environmentId>

When and details

When: GET /experiences/{experienceId}, PUT /experiences/{experienceId}, or DELETE /experiences/{experienceId} references an experience that does not exist in the environment

Details: None.

404

NOT_FOUND

NOT_FOUND

Message: Failed to retrieve environment followed by the environment service’s error message.

When and details

When: Any operation references an environment that does not exist

Details: Detail with code and target environment taken from the backing environment service’s error response. A GET /experiences?name="{experienceName}" request that matches no experience returns an empty list, not 404