User linked accounts


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.

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, which is the identifier for the user’s external identity provider account.
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.

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.

Endpoint examples

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

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:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0/linkedAccounts"
        }
    },
    "_embedded": {
        "linkedAccounts": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0/linkedAccounts/92713768-50f5-4c7a-829f-865c4820d201"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e"
                    },
                    "user": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0"
                    }
                },
                "id": "92713768-50f5-4c7a-829f-865c4820d201",
                "environment": {
                    "id": "6e4b6b42-b73f-4d03-9871-24e7b26a290e"
                },
                "user": {
                    "id": "b7b3bdd6-a3aa-423f-9921-7f8ce13003d0"
                },
                "identityProvider": {
                    "id": "550d3bdf-554b-4f9d-8825-ece15308673d"
                },
                "externalId": "127152908468744"
            }
        ]
    },
    "count": 1,
    "size": 1
}

This request supports the expand filter parameter on the identityProviders attribute so that you can see details about the external identity provider associated with each linked account. The following sample shows the GET /environments/{environmentId}/users/{userId}/linkedAccounts operation with link expansion on identityProviders.

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

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0/linkedAccounts"
        }
    },
    "_embedded": {
        "identityProviders": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/identityProviders/550d3bdf-554b-4f9d-8825-ece15308673d"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e"
                    },
                    "attributes": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/identityProviders/550d3bdf-554b-4f9d-8825-ece15308673d/attributes"
                    }
                },
                "id": "550d3bdf-554b-4f9d-8825-ece15308673d",
                "environment": {
                    "id": "6e4b6b42-b73f-4d03-9871-24e7b26a290e"
                },
                "type": "FACEBOOK",
                "name": "Facebook IdP"
            }
        ],
        "linkedAccounts": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0/linkedAccounts/92713768-50f5-4c7a-829f-865c4820d201"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e"
                    },
                    "user": {
                        "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0"
                    }
                },
                "id": "92713768-50f5-4c7a-829f-865c4820d201",
                "environment": {
                    "id": "6e4b6b42-b73f-4d03-9871-24e7b26a290e"
                },
                "user": {
                    "id": "b7b3bdd6-a3aa-423f-9921-7f8ce13003d0"
                },
                "identityProvider": {
                    "id": "550d3bdf-554b-4f9d-8825-ece15308673d"
                },
                "externalId": "127152908468744"
            }
        ]
    },
    "count": 1,
    "size": 1
}

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. This request also supports the expand=identityProviders filter to show details about the external identity provider associated with this linked account resource.

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

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0/linkedAccounts/92713768-50f5-4c7a-829f-865c4820d201"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/6e4b6b42-b73f-4d03-9871-24e7b26a290e/users/b7b3bdd6-a3aa-423f-9921-7f8ce13003d0"
        }
    },
    "id": "92713768-50f5-4c7a-829f-865c4820d201",
    "environment": {
        "id": "6e4b6b42-b73f-4d03-9871-24e7b26a290e"
    },
    "user": {
        "id": "b7b3bdd6-a3aa-423f-9921-7f8ce13003d0"
    },
    "identityProvider": {
        "id": "550d3bdf-554b-4f9d-8825-ece15308673d"
    },
    "externalId": "127152908468744"
}

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.