PingOne Platform APIs

Deployment

The PingOne /v1/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, refer to 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, refer to 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. Refer to 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.

API service deployment errors

In addition to the general error codes, API service deployment operations can return the following errors:

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

400

INVALID_REQUEST

None

Message: Deployment already in progress with status of "<deploymentStatusCode>" where the status is one of POLICIES_CREATE_IN_PROGRESS, DECISION_ENDPOINT_CREATE_IN_PROGRESS, DECISION_ENDPOINT_UPDATE_IN_PROGRESS, or DECISION_ENDPOINT_DELETE_IN_PROGRESS

When and details

When: A POST /apiServers/{apiServerID}/deployment request targets an API service whose deployment is already in progress

Details: None

400

INVALID_REQUEST

None

Message: Cannot deploy an API service with authorization server type PINGONE_SSO without a PingOne Resource configured.

When and details

When: A POST /apiServers/{apiServerID}/deployment request targets an API service with an authorizationServer.type of PINGONE_SSO that has no PingOne resource configured

Details: None

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The permissions access rule is incompatible with API services created with the GATEWAY deployment type when operations use application permission rules, A policy is incompatible with API services created with the GATEWAY deployment type when a custom policy version is not supported by the deployed Authorize gateways, or the message returned by the Authorize gateway deployment service for other gateway compatibility failures

When and details

When: A POST /apiServers/{apiServerID}/deployment request deploys an API service with the GATEWAY deployment type whose operations use application permission rules, or whose policy version is not compatible with the deployed Authorize gateways

Details: CONSTRAINT_VIOLATION with the same message for locally detected incompatibilities, or the constraint details returned by the Authorize gateway deployment service

400

REQUEST_FAILED

UNIQUENESS_VIOLATION or CONSTRAINT_VIOLATION, among others

Message: <failure step>: <message from the failing operation>, or, for a failure with no API error to report, the message of the underlying failure. For example:

Failed to create a decision endpoint for the API service: The request could not be completed. One or more validation errors were in the request.
When and details

When: A POST /apiServers/{apiServerID}/deployment request fails while creating or updating the API service’s decision endpoint, tagging the authorization version, retrieving trust framework state, or deploying the policy configuration to Authorize gateways

Details: The error details returned by the failing operation — for example UNIQUENESS_VIOLATION with The name '<decisionEndpointName>' is already in use. for a decision endpoint name collision, or CONSTRAINT_VIOLATION details for an invalid policy configuration — or None if the failure carries no details. The failed deployment is recorded on the API service, and the GET operation reports it in status.error

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the authz:read:apiServerDeployment permission (GET operations) or the authz:deploy:apiServerDeployment permission (POST)

Details: None

404

NOT_FOUND

None

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

When and details

When: The apiServerID does not identify an API service in the environment

Details: None