Linked Accounts

The linked accounts endpoints manage a user’s account links to external identity provider accounts. In an authentication flow, after successful authentication at the external identity provider, a linked account resource is created to establish the connection between the user resource in the PingOne directory and that user’s external identity provider account. These endpoints can also be used to view and remove linked accounts in delegated administration or self-service cases.

Users who authenticate with an authoritative identity provider cannot self-service their linked accounts. These users have the identityProvider.id attribute set and their identityProvider.type is not PING_ONE.

Users linked accounts request data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`attributes.{{attributeName}}`	Object	Optional	Mutable	An object that specifies an optional user attribute to update when linking the user. These are mapped user attribute names and values from the external identity provider that are used to update the user.
`externalId`	String	Required	Mutable	A string that specifies the external ID, which is the identifier for the user’s external identity provider account.
`identityProvider.id`	String	Required	Mutable	A string that specifies the external identity provider ID associated with the user to which the user has a linked account.

attributes.{{attributeName}}

Object

Optional

Mutable

An object that specifies an optional user attribute to update when linking the user. These are mapped user attribute names and values from the external identity provider that are used to update the user.

externalId

String

Required

Mutable

A string that specifies the external ID, which is the identifier for the user’s external identity provider account.

identityProvider.id

String

Required

Mutable

A string that specifies the external identity provider ID associated with the user to which the user has a linked account.

Users linked accounts response data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`environment.id`	String	Required	Read-only	A string that specifies the environment associated with the user’s linked account.
`externalId`	String	Required	Read-only	A string that specifies the external ID, which is the identifier for the user’s external identity provider account.
`id`	String	Required	Read-only	A string that specifies the linked account ID associated with the user resource ID identified in the request URL.
`identityProvider.id`	String	Required	Read-only	A string that specifies the external identity provider ID associated with the user to which the user has a linked account.
`user`	Object	Required	Read-only	An `_embedded` object that specifies the user associated with the linked account.
`user.id`	String	Required	Read-only	A string that specifies the user ID associated with the linked account.

environment.id

String

Required

Read-only

A string that specifies the environment associated with the user’s linked account.

externalId

String

Required

Read-only

A string that specifies the external ID, which is the identifier for the user’s external identity provider account.

id

String

Required

Read-only

A string that specifies the linked account ID associated with the user resource ID identified in the request URL.

identityProvider.id

String

Required

Read-only

A string that specifies the external identity provider ID associated with the user to which the user has a linked account.

user

Object

Required

Read-only

An _embedded object that specifies the user associated with the linked account.

user.id

String

Required

Read-only

A string that specifies the user ID associated with the linked account.

Response codes

Code	Message
200	Successful operation.
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.

Linked account errors

In addition to the general error codes, linked account operations can return the following errors:

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

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`EMPTY_VALUE`	Message: `Validation Error : [externalId must not be null]` When and details When: A `POST /users/{ID}/linkedAccounts` request body omits `externalId` Details: Describes the failing property.
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 /users/{ID}/linkedAccounts` request omits `identityProvider.id`, or references an identity provider that does not exist in the environment Details: `The identity provider does not exist.`
400	`REQUEST_FAILED`	`ACCOUNT_NOT_USABLE`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST /users/{ID}/linkedAccounts` request links an account to a disabled user Details: `The user is disabled`
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 /users/{ID}/linkedAccounts` request would link a second authoritative account, or an account already linked to another user; a `DELETE /users/{ID}/linkedAccounts/{ID}` request targets the account of a user with an authoritative identity provider or an account of type `AUTHORITATIVE`; or the target user is an invite (`lifecycle.status` of `INVITED`) Details: `An authoritative account is already linked to the user` or `The account is already linked to another user` (with the linked user’s ID in the inner error); `Authoritative accounts cannot be unlinked` on delete; `Operation not allowed for users with an authoritative identity provider.` on the self-service delete; or `Operation not allowed for users with lifecycle.status INVITED` for an invite.
400	`INVALID_DATA`	`SIZE_LIMIT_EXCEEDED`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /users/{ID}/linkedAccounts` request exceeds the environment’s maximum number of linked accounts per user Details: `Exceeded maximum number of linked accounts for the user. The maximum is <maximum>`
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 /users/{ID}/linkedAccounts` request supplies `attributes.memberOfExternalGroups` in a format that is not an array of objects Details: `Invalid format for memberOfExternalGroups. The attribute must be an array of objects.`
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 /users/{ID}/linkedAccounts` request supplies `attributes.memberOfExternalGroups` whose objects fail external group validation (for example, an object without a `name` property) Details: `All external groups in the request must have a name`
400	`INVALID_REQUEST`	`INVALID_VALUE` or None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A request body cannot be deserialized as JSON Details: For a JSON field conversion error, the detail is `Invalid value for attribute.` with target = the field path. Otherwise no detail is returned.
400	`INVALID_REQUEST`	None	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A path identifier cannot be parsed as a UUID 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 `dir:create:userLinkedAccounts` permission (`POST` operations), the `dir:read:userLinkedAccounts` permission (`GET` operations), or the `dir:delete:userLinkedAccounts` permission (`DELETE` operations), or is not authorized for the target user’s population or group scope Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: The user ID, environment ID, or linked account ID in the request URL does not exist Details: None.
500	`UNEXPECTED_ERROR`	None	Message: `There was an unexpected error with the service. Please try again later.` When and details When: A `POST /users/{ID}/linkedAccounts` request completes the link, but the created linked account cannot be read back. The specific failure is logged, not returned Details: None.

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [externalId must not be null]

When and details

When: A POST /users/{ID}/linkedAccounts request body omits externalId

Details: Describes the failing property.

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 /users/{ID}/linkedAccounts request omits identityProvider.id, or references an identity provider that does not exist in the environment

Details: The identity provider does not exist.

400

REQUEST_FAILED

ACCOUNT_NOT_USABLE

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

When and details

When: A POST /users/{ID}/linkedAccounts request links an account to a disabled user

Details: The user is disabled

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 /users/{ID}/linkedAccounts request would link a second authoritative account, or an account already linked to another user; a DELETE /users/{ID}/linkedAccounts/{ID} request targets the account of a user with an authoritative identity provider or an account of type AUTHORITATIVE; or the target user is an invite (lifecycle.status of INVITED)

Details: An authoritative account is already linked to the user or The account is already linked to another user (with the linked user’s ID in the inner error); Authoritative accounts cannot be unlinked on delete; Operation not allowed for users with an authoritative identity provider. on the self-service delete; or Operation not allowed for users with lifecycle.status INVITED for an invite.

400

INVALID_DATA

SIZE_LIMIT_EXCEEDED

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

When and details

When: A POST /users/{ID}/linkedAccounts request exceeds the environment’s maximum number of linked accounts per user

Details: Exceeded maximum number of linked accounts for the user. The maximum is <maximum>

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 /users/{ID}/linkedAccounts request supplies attributes.memberOfExternalGroups in a format that is not an array of objects

Details: Invalid format for memberOfExternalGroups. The attribute must be an array of objects.

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 /users/{ID}/linkedAccounts request supplies attributes.memberOfExternalGroups whose objects fail external group validation (for example, an object without a name property)

Details: All external groups in the request must have a name

400

INVALID_REQUEST

INVALID_VALUE or None

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

When and details

When: A request body cannot be deserialized as JSON

Details: For a JSON field conversion error, the detail is Invalid value for attribute. with target = the field path. Otherwise no detail is returned.

400

INVALID_REQUEST

None

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

When and details

When: A path identifier cannot be parsed as a UUID

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 dir:create:userLinkedAccounts permission (POST operations), the dir:read:userLinkedAccounts permission (GET operations), or the dir:delete:userLinkedAccounts permission (DELETE operations), or is not authorized for the target user’s population or group scope

Details: None.

404

NOT_FOUND

None

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

When and details

When: The user ID, environment ID, or linked account ID in the request URL does not exist

Details: None.

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: A POST /users/{ID}/linkedAccounts request completes the link, but the created linked account cannot be read back. The specific failure is logged, not returned

Details: None.

For linked accounts endpoint operations, you need the Identity Data Admin role to get or delete linked account resources.

PingOne Platform APIs

Linked Accounts

Users linked accounts request data model

Users linked accounts response data model

Response codes

Linked account errors