PingOne Platform APIs

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, refer to Roles.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

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 CIAM (Customer Identity Access Management) trial experience. Indicates the Customer solution type, and the Solution Designer were selected.

  • WF_TRIAL. The Workforce trial experience. Indicates the Workforce solution type, and the Solution Designer were selected.

  • CUSTOMER. Indicates the Customer solution type was selected.

  • WORKFORCE. Indicates the Workforce solution type was selected.

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_AUTHORIZE, PING_ONE_BASE, PING_ONE_CREDENTIALS, PING_ONE_DAVINCI, PING_ONE_ID (v2 customers), PING_ONE_MFA, PING_ONE_PROVISIONING, PING_ONE_RISK (this name also represents the PingOne Protect product), and PING_ONE_VERIFY.

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_ACCESS, PING_AUTHORIZE, PING_CENTRAL, PING_DATA_GOVERNANCE, PING_DATA_SYNC, PING_DIRECTORY, PING_FEDERATE, PING_ID (v1 customers), PING_ID_SDK, PING_INTELLIGENCE, PING_ONE_FOR_ENTERPRISE, and PING_ONE_FOR_SAAS.

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.

subtype

String

Optional

Immutable

Specifies the solution context when the type is PING_ONE_MFA. This field indicates whether the environment’s authentication flow is configured for customers (CIAM) or employees (WORKFORCE). Options are:

  • CIAM

  • WORKFORCE

Important: Use this field to determine the active MFA configuration. Do not rely on solutionType, or other license-level fields because those only represent the environment’s initial creation context and might not reflect its current state.

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.

The other Ping Identity products identified in the products.type property are not hosted on the PingOne platform. These products are not subject to any licensing restrictions when they are added or removed from the BOM. Conversely, PingOne platform products are hosted on the platform and are subject to licensing restrictions when they are added to the BOM.

Bill of Materials events generated

Refer to Audit Reporting Events for the events generated.

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.

Bill of Materials errors

In addition to the general error codes, Bill of Materials 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

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

When and details

When: A PUT /billOfMaterials request supplies an invalid product, bookmark, or console value: a products entry with no type, a bookmark name that is empty or longer than 50 characters, more than five bookmarks for a product, more than 100 products, or a console.href that is empty or longer than 1024 characters

Details: must not be null for a products entry with no type, size must be between 1 and 50 for a bookmark name that is empty or longer than 50 characters, size must be between 0 and 5 for a product with more than five bookmarks, size must be between 0 and 100 for more than 100 products, or size must be between 1 and 1024 for a console.href that is empty or longer than 1024 characters, for example Validation Error : [products[0].type must not be null] or Validation Error : [products size must be between 0 and 100].

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /billOfMaterials request supplies a products.type value that is not a supported product type, or a products.subtype value that is not a supported subtype

Details: Must only contain one among the the values: <supported values> (product types or subtypes), for example Validation Error : [billOfMaterials.products[0].type Must only contain one among the the values: <supported values>]

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /billOfMaterials request supplies a console.href or bookmarks.href value that is not an RFC 2396-compliant URI

Details: Must contain a valid RFC 2396-compliant URI, for example Validation Error : [billOfMaterials.products[0].console.href Must contain a valid RFC 2396-compliant URI]

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: Bill of Materials contains duplicate products

When and details

When: A PUT /billOfMaterials request includes more than one product with the same type among the platform products, or a duplicate PING_ONE_ADVANCED_SERVICES_SELF_SERVICE product

Details: Bill of Materials contains more than one product of type <productType>

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /billOfMaterials request includes two bookmarks with the same name for a product, or two identical product tags

Details: Bookmark names must be unique or Tag names must be unique, for example Validation Error : [bookmarks Bookmark names must be unique]

400

INVALID_REQUEST

None

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

When and details

When: The request body cannot be deserialized (a path identifier that cannot be parsed as a UUID returns 404 instead, because the controller parses the environment ID itself)

Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A PUT /billOfMaterials request violates a composition rule: more than one MFA product (PING_ONE_MFA, PING_ID, or PING_ID_SDK), more than one IDENTITY_CLOUD product, tags on a product that does not support them, a PING_ONE_PAM product without exactly one tag, an invalid tag value, more than one deployment for the same product type, a product type that does not match the referenced deployment’s product type, a deployment already assigned to another environment, a deployment that already has an associated orchestration, or a change to the immutable subtype of an existing product

Details: Describes the rejected composition, such as

Bill of Materials contains more than one MFA product. Bill of Materials can only contain one of [PING_ONE_MFA, PING_ID, PING_ID_SDK]

, Bill of Materials contains more than one IDENTITY_CLOUD product., Tags are only supported on Products with type: PING_ONE_DAVINCI, A single tag is required for product type: PING_ONE_PAM, must be one of the values: <values>, must be one of the values: <values>, Bill of Materials can only have one deployment per product type, The product’s type in the BoM does not match the deployment’s product type, Deployment in Bill of Materials is already assigned to another environment, Deployment in Bill of Materials is already has an associated orchestration, Ping Cloud deployments in the Bill of Materials must all have the same useCaseInstanceType, or subtype cannot be changed after creation

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /billOfMaterials request references a deployment that does not exist in the organization, or that belongs to a different organization

Details: Deployment specified in Bill of Materials was not found

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /billOfMaterials request removes the deployment relationship from a PING_ID or PING_ONE_ID product that has one, or omits such a product from the request

Details: Cannot remove deployment relationship from a PING_ID or PING_ONE_ID product in the Bill of Materials.

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A PUT /billOfMaterials request updates a soft‑deleted environment whose Bill of Materials still contains an active Identity Cloud deployment

Details: Cannot update the Bill of Materials for a Soft Deleted environment with an active Identity Cloud deployment.

400

INVALID_DATA

INVALID_VALUE

Message: Environment not licensed for one or more products in Bill of Materials

When and details

When: A PUT /billOfMaterials request adds one or more products that the environment’s license does not include, including the deprecated PingOne Fraud product

Details: Environment is not licensed for <productType>, one detail per unlicensed product.

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

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

When and details

When: The actor lacks the orgmgt:read:environment permission (GET), or the orgmgt:update:environment permission (PUT), or is not entitled to the environment’s organization or the environment itself

Details: None.

404

NOT_FOUND

None

Message: Unable to find environment with ID: '<environmentId>'

When and details

When: GET or PUT /billOfMaterials references an environment that does not exist, or the environment ID cannot be parsed as a UUID

Details: None.

429

REQUEST_LIMITED

None

Message: The request could not be completed. A rate or quota limit was reached. Please try again later.

When and details

When: A PUT /billOfMaterials request adds PING_ONE_DAVINCI to an environment that does not already have it. This operation is rate limited per organization

Details: None.