PingOne Platform APIs

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}}/v1/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.

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

Misconfiguring an external IdP can result in a lockout.

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.

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.

Administrator security errors

In addition to the general error codes, administrator security 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: Describes the rejected property, such as Recovery must be provided when updating admin configuration., Authentication method must be provided when updating admin configuration., Provider must not be provided when using authentication method PINGONE., Populations are only applicable if authentication method is HYBRID., Discovery Rules are only applicable if authentication method is HYBRID., or MFA Status must be provided when updating admin configuration.

When and details

When: A POST or PUT /adminConfig request omits or supplies an invalid value for a required property on update: recovery, authenticationMethod, mfaStatus, or a property that conflicts with the configured method, such as provider with PINGONE or populations and discoveryRules with a method other than HYBRID

Details: None.

400

INVALID_REQUEST

None

Message: MFA status must be ENFORCE.

When and details

When: A PUT /adminConfig request changes mfaStatus from ENFORCE to another value

Details: None.

400

INVALID_REQUEST

None

Message: Describes the rejected configuration, such as Allowed methods must include EMAIL, TOTP, and FIDO2., Enabled must be provided for method: <method>, Error processing allowed methods JSON for method: <method>, At least one method must be enabled., or FIDO2 is not available for this environment.

When and details

When: A PUT /adminConfig request supplies an allowedMethods configuration that is invalid: missing one of EMAIL, TOTP, or FIDO2, a method entry without an enabled value or with malformed JSON, no methods enabled, or FIDO2 enabled in an environment that does not support it

Details: None.

400

INVALID_REQUEST

None

Message: Discovery Rules exceeds the maximum limit of <maximum>

When and details

When: A PUT /adminConfig request with a HYBRID method supplies more discovery rules than the environment allows

Details: None.

400

INVALID_REQUEST

None

Message: Admin configuration is not enabled for the organization or environment.

When and details

When: A POST /adminConfig request is made for an organization or environment that does not have the administrator MFA configuration enabled

Details: None.

400

INVALID_REQUEST

None

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

When and details

When: A POST or PUT /adminConfig request body cannot be deserialized, for example an unrecognized authenticationMethod or mfaStatus value

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

400

REQUEST_FAILED

None

Message: Admin configuration for environment ID <environmentId> already exists. or Provider must be provided when using the authentication method EXTERNAL. (or Provider must be provided when using an authentication method other than PINGONE.)

When and details

When: A POST /adminConfig request creates a configuration for an environment that already has one, or supplies an external or hybrid method without a provider

Details: None.

400

REQUEST_FAILED

None

Message: Describes the failed operation, such as Error creating admin configuration for environment ID <environmentId>., Error updating admin configuration for environment ID <environmentId>., Error reading admin configuration for environment ID <environmentId>., Error retrieving environment with ID <environmentId>., Error retrieving identity provider with ID <providerId>., Error retrieving population with ID <populationId>., or Error retrieving provider with ID <providerId>.

When and details

When: The request cannot be completed because of a downstream service failure while validating or storing the configuration

Details: None.

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the admin:read:config permission (GET), the admin:create:config permission (POST), or the admin:update:config permission (PUT)

Details: None.

404

NOT_FOUND

None

Message: Environment with ID <environmentId> does not exist. or Admin configuration for environment ID = <environmentId> not found.

When and details

When: A PUT /adminConfig request references an environment that does not exist, or updates a configuration that has not been created

Details: None.

404

NOT_FOUND

None

Message: Identity provider with ID <providerId> does not exist., Population with ID <populationId> does not exist., Provider with ID <providerId> does not exist., or Identity provider with ID <providerId> is not enabled.

When and details

When: A POST or PUT /adminConfig request references an identity provider, population, or discovery‑rule provider that does not exist, or an identity provider that is disabled

Details: None.