Overview
When using third-party IdPs, there might be the need to access the IdP’s API on behalf of the user.
This article details how can one retrieve the access tokens, given that they are not directly available from the user profile.
Applies To
- Access Tokens
- Retrieve Access Tokens
Solution
Identity provider access tokens are accessible via the management API. They will be present in the response from the Get a user endpoint so long as read:user_idp_tokens is present in addition to the required read:users scope.
How it is recommended to retrieve and use IdP access tokens depends on whether the application is a backend or frontend application.
For Backend Applications
- Obtain a management API token.
- Create a Machine-to-Machine application in the dashboard that will use the management API.
- Grant the following scopes to the application:
- read:users
- read:user_idp_tokens
- Use the client credentials flow while specifying the read:users and read:user_idp_tokens scopes to retrieve an access token for the management API.
- See Get Management API Access Tokens for Production for more details on retrieving management API tokens.
- Retrieve the user profile
- Call the Get a user endpoint using the access token from step 1: https:///api/v2/users/<user id>
- Extract the IdP access token and refresh token (where applicable).
- The IdP access token is usually found at user.identities[0].access_token, assuming there is only a single identity. In the case of linked accounts it could be in another element of the identities array.
- For IdPs that support refresh tokens (this works for BitBucket, Google, OAuth 2.0, SharePoint, and Azure AD), the refresh token can be retrieved from user.identities[0].refresh_token.
For Frontend Applications
For security reasons, frontend applications cannot directly retrieve IdP tokens.
We also recommend not exposing IdP tokens to the frontend. Instead, we recommend creating a proxy API that uses the process described in the “For Backend Services” section above.
The proxy API can then obtain the management API token and perform API calls on behalf of the front end.