PingOne Platform APIs

External Groups

External groups are groups that originate outside of PingOne. An external group is created using a Just In Time (JIT) method by setting the memberOfExternalGroups property when adding a new user. Refer to the Users data model for more information.

External group constraints

As opposed to internal PingOne groups, there are a few things external groups cannot do:

  • Cannot set a dynamic filter.

  • Cannot have nested groups

  • Cannot edit group memberships

Errors will occur if:

  • The total number of internal and external groups exceeds 100,000.

  • The total number of groups for a user exceeds 10,000.

External groups data model

Property Type Required Description

groups

Object[]

Required

A batch of groups that have been changed since the last delta.

groups.attributes

Map

Required

A multi valued map of attribute names and values.

groups.operation

String

Optional

The optional source change operation. Either CREATED, UPDATED, or DELETED to be provided when the gateway agent is performing a change detection on the token starting point.

groups.uniqueId

String

Required

The unique identifier of the group.

nextToken

String

Optional

An optional token indicating this is the last batch of groups and the starting point to request changes on the next poll request.

startToken

String

Optional

An optional token indicating the starting point of group changes. If null all groups will eventually be received through multiple requests.

External group errors

In addition to the general error codes, external group import 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 request omits a group’s uniqueId, or supplies a groups.operation value other than CREATED, UPDATED, or DELETED

Details: must not be empty or Invalid status value., for example Validation Error : [status Invalid status value.]

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [groups users must not exceed 100]

When and details

When: A POST request supplies a batch of more than 100 groups

Details: users must not exceed 100

400

INVALID_DATA

None

Message:

The provisioning sync orchestration=<provisioningSyncID> must have an IN_PROGRESS or RESYNC_IN_PROGRESS status to sync users, but the current state is <status>
When and details

When: A POST request references a provisioning sync orchestration whose group sync status is not IN_PROGRESS or RESYNC_IN_PROGRESS

Details: None.

400

INVALID_DATA

None

Message: Unable to resolve enabled rule within plan revision=<planRevisionID> for environment <envID>

When and details

When: A POST request references a provisioning sync whose rule is missing or disabled in the current plan revision

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 provisioning:update:provisioningSyncOrchestration permission (POST operations)

Details: None.

404

NOT_FOUND

None

Message: Unable to find provisioning sync orchestration=<provisioningSyncID> with environment=<envID>, or Unable to find provisioning sync rule=<ruleID> with environment=<envID>, or Rule id <ruleID> not found in PlanRevision for envID <envID>, or Feature flag <flagName> prevents handling this request for environment=<envID>

When and details

When: A POST request references a provisioning sync ID that does not exist in the environment, a sync rule that has no orchestration state, a rule that does not exist in the plan revision, or the environment does not have the inbound group provisioning feature enabled

Details: None.