PingOne Platform APIs

Populations

In PingOne, populations are similar to an organizational unit (OU) and are used to simplify user and policy management within a given environment. For example, you can create a population for similar types of users, such as those in a particular geography or job function, and assign those users a unique password policy.

The /v1/environments/{{envID}}/populations endpoint provides operations to create, read, update, and delete population resources within a specified environment.

Before you can create users, you must have at least one existing population. When you create a user, you can assign them to a specified population. If you do not specify a population, PingOne adds the new user to the default population. You can configure any population to be the default population, either at the time of creation or at a later time.

Individual users cannot belong to more than one population within a PingOne environment. However, you can move users to a different population within the existing environment.

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.

Populations data model

Property Type Required Mutable Description

alternativeIdentifiers

String[]

Optional

Mutable

Alternative identifiers that can be used to search for populations besides name. There’s a 255 character limit, and a limit of 100 alternative identifiers per population.

createdAt

Date

N/A

Read-only

The time the resource was created.

default

String

Required

Mutable

The population to use as the default population for the environment. Only one population per environment can be the default. New users are assigned to the default population if it exists, and the Population ID is not provided in the Create User request.

description

String

Optional

Mutable

The description of the population.

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the population.

id

String

Required/Optional

Immutable

The resource’s unique identifier. This is optional if you’re setting PingOne as the default identity provider using PUT Update Population Default IdP.

name

String

Required

Mutable

The population name, which must be provided and must be unique within an environment.

preferredLanguage

String

Optional

Mutable

The language locale for the population. If absent, the environment default is used.

updatedAt

Date

N/A

Read-only

The time the resource was last updated.

userCount

Integer

N/A

Read-only

The number of users that belong to the population.

passwordPolicy

Object

Optional

Mutable

The object reference to the password policy resource.

passwordPolicy.id

String

Optional

Immutable

The ID of the password policy that is used for this population. If absent, the environment’s default is used.

theme

Object

Optional

Mutable

The object reference to the theme resource.

theme.id

String

Optional

Immutable

The ID of the theme to use for the population. If absent, the environment’s default is used.

Populations events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

404

The requested resource was not found.

Population errors

In addition to the general error codes, population 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 INVALID_VALUE

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

When and details

When: A POST or PUT /populations request omits name, provides an empty name, or provides a name with characters other than Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens

Details: Describes the failing property, such as must not be null for an omitted name, must not be empty for an empty name, must not be empty or blank for a whitespace-only name, or must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for a name with impermissible characters, for example Validation Error : [name must not be empty or blank]

400

INVALID_DATA

UNIQUENESS_VIOLATION

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

When and details

When: A POST /populations request creates a population with a name that duplicates an existing population in the environment, or a PUT /populations/{ID} request renames the population to one that does

Details: A population with the specified name already exists.

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 POST or PUT /populations request provides an alternativeIdentifiers array with duplicate elements (case-insensitive), or a preferredLanguage value that is not a valid language locale, that does not exist in the environment, or that is not enabled

Details: must only contain unique elements, invalid language locale, language locale does not exist in the environment, or language locale is not enabled

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 POST or PUT /populations request references a password policy that does not exist in the environment

Details: invalid passwordPolicy value was provided

400

INVALID_DATA

INVALID_VALUE or EMPTY_VALUE

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

When and details

When: A POST or PUT /populations request references a theme that does not exist in the environment, or provides an empty or blank theme.id

Details: invalid value was provided or must not be empty or blank

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A POST /populations request would exceed the maximum number of populations allowed in the environment (10,000 by default)

Details: Cannot create more than <maximum> populations in this environment.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A POST or PUT /populations request provides an alternativeIdentifiers array with more than 100 entries

Details: size cannot exceed <maximum>

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A DELETE /populations/{ID} request targets a population that contains users or groups, a PUT /populations/{ID} request changes defaultIdentityProvider, or a DELETE request targets the last population in the environment or the environment’s default population

Details: Population must not contain any users before it may be deleted, Population must not contain any groups before it may be deleted, An environment must contain at least one population, Cannot delete default population, or is immutable and cannot be updated

400

REQUEST_FAILED

INVALID_PARAMETER

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

When and details

When: A GET /populations request has a limit query parameter less than 1 or greater than 1000

Details: Must be between 1 and 1000

400

REQUEST_FAILED

INVALID_FILTER

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

When and details

When: A GET /populations request uses a filter expression that cannot be parsed, or a filter on an attribute that does not support filtering

Details: The value provided is invalid. or The filter attribute was invalid or does not support filtering.

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the dir:create:population permission (POST), the dir:read:population permission (GET), the dir:update:population or dir:update:userIdentityProvider permission (PUT), or the dir:delete:population permission (DELETE), or the actor is population-scoped and is not authorized for the target population

Details: None.

404

NOT_FOUND

None

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

When and details

When: A GET, PUT, or DELETE /populations/{ID} request references a population or an environment that does not exist

Details: None.