PingOne Platform APIs

Early Access Features

You can 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.

Your ability to participated in Early Access is determined by the licensing for your account, the bill of materials for your account, your assigned role for the PingOne environment (Environment Admin role is required), and whether the PingOne service or services affected by the early access feature or features are available in the environment.

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.

Early access feature errors

In addition to the general error codes, early access feature operations can return the following errors:

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

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A PUT /environments/{ID}/earlyAccessFeatures request omits the required features property, or a feature in the features array omits or blanks name or segmentKey

Details: must not be null for features; Name Cannot be null or Name cannot be blank for a feature name; Segment Key Cannot be null or Segment Key cannot be blank for a feature segmentKey, for example Validation Error : [features[0].name Name Cannot be null]

400

INVALID_REQUEST

INVALID_REQUEST

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

When and details

When: A PUT /environments/{ID}/earlyAccessFeatures request sends an empty features array, sends the same segmentKey more than once, requests a feature that is already opted in or already opted out, requests a feature whose segmentKey does not exist, requests a feature that is not available to the environment, or is made for an environment whose license has expired

Details: One of No Features sent for EnvironmentId <environmentId>, Duplicate features found in the request for EnvironmentId <environmentId>, The following features are missing: <segmentKey>, or The following features are not available for environmentId <environmentId>: <segmentKeys> with target segments, Feature <segmentKey> already opted in for environmentId <environmentId>, Feature <segmentKey> already opted out for environmentId <environmentId>, or Segment value not found for segment: <segmentKey> with target envId, or license expired for environmentId <environmentId> with target license

400

INVALID_REQUEST

INVALID_REQUEST

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

When and details

When: GET /environments/{ID}/earlyAccessFeatures uses a licenseId query parameter and the license cannot be retrieved with that ID

Details: error while fetching license for licenseId <licenseId>. Error: <message> with target license

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request. for an unparseable environment ID, or The request could not be completed. The request was malformed or invalid. for an unparseable body.

When and details

When: The environment ID in the request path cannot be parsed as a UUID, or the request body cannot be parsed as JSON

Details: For an unparseable body, the detail is Invalid value for attribute. with the JSON field path as the target.

400

REQUEST_FAILED

REQUEST_FAILED

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

When and details

When: The early access feature update cannot be completed because the LaunchDarkly segment cannot be retrieved or updated, or the request fails unexpectedly

Details: One of Error while fetching segment details from LD <segmentKey> with target segment, Failed to update segment: <segmentKey> with target envId, or:

An unexpected error occurred while updating early access features for the environment. Please contact support if the issue persists

with target update

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the earlyAccess:read:features permission (GET operations) or the earlyAccess:update:features permission (PUT operations)

Details: None.

404

NOT_FOUND

NOT_FOUND

Message: The request could not be completed. The requested resource was not found.

When and details

When: GET or PUT /environments/{ID}/earlyAccessFeatures references an environment that does not exist, the read request cannot find any LaunchDarkly segments tagged EarlyAccess, or a segment listed for the environment cannot be found in LaunchDarkly during a read

Details: Failed to retrieve environment: <message> with target environment for an unknown environment, No segments found for tags <filter> with target segments for the read request, or No segment found for segment key <segmentKey> with target segment for a missing segment

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: A request fails unexpectedly outside the handled error paths, such as a LaunchDarkly feature flag lookup failing while reading the environment’s features

Details: None.