User linked accounts


Linked accounts

The user 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, linked account resources identify the user in the directory that is linked to an external identity provider account. These endpoints can also be used to view and remove linked accounts in delegated administration or self-service cases.

Account linking recognizes the following two external account types:

  • Authoritative

    The account at the identity provider is the authoritative source of profile data and authentication credentials for this user. This user is managed at the external identity provider. This option is used primarily for SAML federation, where the source of truth for the user’s account is the external identity provider. These links cannot be deleted.

  • Social

    The account at the external identity provider is another identity that represents this user. This user is managed by PingOne for Customers.

User linked accounts API operations

The user linked accounts endpoints support the following operations:

For hands-on experience with the user linked accounts API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Users linked accounts data model

Property Description
environment.id A string that specifies the environment associated with the user’s linked account.
externalId A string that specifies the external ID for the external identity provider to which the user account is linked.
id A string that specifies the linked account ID associated with the user resource ID identified in the request URL.
identityProvider.id A string that specifies the external identity provider ID associated with the user to which the user has a linked account.
user.id A string that specifies the user associated with the linked account.
type A string that specifies the type of linked account ID associated with the user resource ID. Options are AUTHORITATIVE and SOCIAL.

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.

Endpoint examples

Get user linked accounts

To get the linked accounts associated with a single user resource, the GET /environments/{environmentId}/users/{userId}/linkedAccounts operation returns the linked accounts for the user resource with the ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/linkedAccounts" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

Data here

Get one user linked account

To get information about one linked account associated with a single user resource, the GET /environments/{environmentId}/users/{userId}/linkedAccounts/{linkedAccountId} operation returns the linked account information for the linked account resource specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/linkedAccounts/{linkedAccountId}" \
-H "Authorization: Bearer jwtToken"

Create user linked accounts

The following sample shows the POST /environments/{environmentId}/users/{userId}/linkedAccounts operation to link an external identity provider account to the user if the user is not already linked. This operation can also be used to update the user’s attributes based on the attributes returned by the external identity provider. This operation uses the application/vnd.pingidentity.account.link+json custom media type as the content type in the request header.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/linkedAccounts" \
-H 'Content-type: application/vnd.pingidentity.account.link+json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
   "type":"SOCIAL",
   "identityProvider":{  
      "id":"852ff10e-4747-4309-ae91-5387421fbc40"
   },
   "externalId":"3249023841",
   "attributes":{  
      "username":{  
         "value":"bob@bob.com",
         "update":"EMPTY_ONLY"
      },
      "email":{  
         "value":"bob@bob.com",
         "update":"EMPTY_ONLY"
      },
      "name.first":{  
         "value":"Bob",
         "update":"ALWAYS"
      },
      "name.last":{  
         "value":"Smith",
         "update":"EMPTY_ONLY"
      }
   }
}'

The response data looks like this:

{
   "_links": {
     ...
   },  
   "id":"21896def-8878-4646-2121-aa91a14a6769",
   "environment":{  
     "id":"66c23def-39c9-4646-8d41-aa91a14a1006"
   },
   "user":{
     "id":"8ce55f02-2077-4493-9a6d-0385df1f0772"
   },
   "type":"SOCIAL",
   "identityProvider":{  
      "id":"852ff10e-4747-4309-ae91-5387421fbc40"
   },
   "externalId":"3249023841",
  }

Delete linked accounts

The following sample shows the DELETE /environments/{environmentId}/users/{userId}/linkedAccounts/{linkedAccountId} operation to delete the linked account specified by its ID in the request URL. The linked account is deleted for the user identified in the request URL.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/linkedAccounts/{linkedAccountId}" \
-H "Authorization: Bearer jwtToken" \

When successful, the DELETE request returns a code 204 No Content message.