If you have Token Vault enabled for your connection, access and refresh tokens will no longer be stored in the user’s identities array. Instead, they will be stored in a secure tokenset within the Token Vault. To enable Token Vault, read Configure Token Vault.
Once you successfully authenticate a user with an external (IdP), such as Facebook or GitHub, the IdP often includes an in the user profile it returns to Auth0. You can retrieve and use this token to call the IdP’s API.
This article assumes that you have already configured the connection with the IdP of your choice. If not, go to Identity Providers Supported by Auth0, select the IdP you want, and follow the configuration steps.
The process you will follow differs depending on whether your code runs in the backend or the frontend:
  • If your code runs in the backend, then we can assume that your server is trusted to safely store secrets (as you will see, we use a secret in the backend scenario). If that’s the case, proceed to the backend section of this article.
  • If your code runs in the frontend (for example, it’s a SPA, native desktop, or mobile app), then your app cannot hold credentials securely and has to follow an alternate approach. In this case, proceed to the frontend section of this article.

​
From the backend

Once you authenticate a user, the IdP often includes an Access Token in the user profile it returns to Auth0. For security and compliance reasons, Auth0 does not send this token to your app as part of the user profile. To get it, you must access the Auth0 and retrieve the full user’s profile:
  1. Get an Access Token that allows you to call the Auth0 Management API.
  2. Call the Auth0 Management API’s Get Users by ID endpoint using the Access Token obtained in step one. This endpoint returns the full user’s profile, which contains the IdP Access Token.
  3. Extract the IdP Access Token from the response and use it to call the IdP’s API.

​
Step 1: Get a Token

You will need an Access Token to call the Management API.

​
Create a test application for the Management API

If this is the first time you are requesting a Management APIv2 Token, you will need to create and configure an application that can be used to call the Management API:
  1. Navigate to Auth0 Dashboard > Applications > APIs, and select the Auth0 Management API.
  2. Select the API Explorer view, and click Create & Authorize a Test Application.
This will create a new application and grant all scopes of the Management API, which means that the tokens generated for this application will be able to access all Management API endpoints.

​
Can’t see the button?

If you don’t see this button, it means that you already have at least one authorized application for the Management API. In this case, you can either update the scopes of the existing application and use that, or create a new one following these steps:
  1. Navigate to Auth0 Dashboard > Applications > Applications, and select Create Application.
  2. Select Machine to Machine Applications, and then Create.
  3. From the Select an API dropdown, select Auth0 Management API.
  4. Enable required scopes, and select Authorize.
  5. Select the APIs view, and enable the toggle for Auth0 Management API.
For security reasons, we recommend that you assign only the required scopes to the application you will be using. For this particular case, the scopes you need are: read:users, read:user_idp_tokens. Required scopes are listed for each endpoint in the Management API Explorer.
To grant or remove scopes from the registered Auth0 Management API, select the Machine to Machine Applications view:
Edit the scopes granted to the Application

​
Get the Management API Token

You are now done with configuration and are ready to get your Management API token:
  1. From the registered Auth0 Management API, select the Test view.
  2. Choose your application from the Application dropdown to pre-populate the ready-to-use snippets with customized variables.
  3. Choose your language of preference for the snippet, and copy and run it.
  4. Extract the access_token property from the response. This is what you will use to access the Management API.

​
What are the snippets doing?

The snippets make a POST operation to the /oauth/token endpoint of the Auth0 Authentication API, using the OAuth 2.0 Client Credentials grant. This is the grant that machine-to-machine processes use to access an API. To learn more about the flow, read Client Credentials Flow.

​
Token expiration

By default, the token you received expires in 24 hours (86,400 seconds). To change this:
  1. Navigate to Auth0 Dashboard > Applications > APIs, and select the Auth0 Management API.
  2. Select the Settings view, locate the Token Expiration (Seconds) field, enter a new value, and click Save. The maximum value you can set is 2,592,000 seconds (30 days), though we recommend that you keep the default value.
The next token you generate will use the updated expiration time.
These tokens cannot be revoked. To minimize risk, we recommend issuing short-lived tokens and granting only the necessary scopes for each application. For a production environment, you can configure a simple CLI that will fetch a new token when the old one expires.

​
Step 2: Get the full User Profile

To get a user’s profile, call the Get a User endpoint of the Management API using the Access Token you extracted in the previous section: 
curl --request GET \
  --url 'https://{yourDomain}/api/v2/users/%7BuserId%7D' \
  --header 'authorization: Bearer {yourAccessToken}'
Replace these values:
  • {userId}: ID of the user for whom you want to call the IdP’s API.
  • {yourAccessToken}: Access Token you extracted in the previous section.

​
Where do I find the User ID?

  • For testing purposes, you can find a user ID at Auth0 Dashboard > User Management > Users. Locate a user, and copy the value of the user_id field.
  • For your implementation, you can either extract the user ID from the sub claim in the ID Token, or call the /userinfo endpoint of the Authentication API and extract it from the user_id response property.

​
Step 3: Extract the IdP Access Token

You can find the Access Token used to call the IdP’s API within the user’s identities array: user.identities[0].access_token.
For certain Identity Providers, Auth0 will also store a Refresh Token, which you can use to obtain a new Access Token for the IdP. This works for: BitBucket, Google (OAuth 2.0), OAuth 2.0, SharePoint, and Azure AD. To learn more, read Identity Provider Access Tokens.
In most cases, the user will only have one identity, but if the user has signed in multiple times through different connections and you have used account linking, there may be more. In this sample response, we see that our user has only one identity: google-oauth2. 
{
  "email": "john.doe@test.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://myavatar/photo.jpg",
  "gender": "male",
  "locale": "en",
  "updated_at": "2017-03-15T07:14:32.451Z",
  "user_id": "google-oauth2|111199914890750704174",
  "nickname": "john.doe",
  "identities": [
    {
      "provider": "google-oauth2",
      "access_token": "ya29.GlsPBCS6ahokDlgCYnVLnDKNE71HBXPEzNhAPoKJLAGKDSe1De3_xclahNcdZXoU-26hCpa8h6240TV86dtaEQ4ZWoeeZduHDq_yeu9QyQqUr--S9B2CR9YJrLTD",
      "expires_in": 3599,
      "user_id": "111199914890750704174",
      "connection": "google-oauth2",
      "isSocial": true
    }
  ],
  "created_at": "2017-03-15T07:13:41.134Z",
  "last_ip": "127.0.0.1",
  "last_login": "2017-03-15T07:14:32.451Z",
  "logins_count": 99
}
You are now ready to call the IdP’s API. Please refer to the IdP’s documentation for specifics on how to do so.
Don’t expose IdP tokens to your client-side application! If your application is public, see the frontend section of this article.
To learn more about how to request specific scopes for an Identity Provider Access Token, read Add scopes/permissions to call Identity Provider’s APIs.

​
From the frontend

If you are working with a public application (SPA, native desktop, or mobile app), then this is the place to be. When working with a frontend app, the process for calling IdP APIs differs from the backend process because frontend apps are public applications that cannot hold credentials securely. Because SPA code can be viewed and altered, and native/mobile apps can be decompiled and inspected, they cannot be trusted to hold sensitive information like secret keys or passwords. Specifically, they cannot securely hold the for the Machine to Machine Application, which you use to call /oauth/token during the first step of the backend process. Instead, you must build a proxy for your backend and expose it to your application as an API.

​
Build a proxy

First, you will build a process in your backend that will implement the steps included in the backend section of this article, and expose it to your application as an API. You will call the IdP’s API from the same backend process, so the Access Token is never exposed to your public application. Then, you will call your proxy API from your public application using the Authorization Code Flow with Proof Key for Code Exchange (PKCE).

​
Show me how

If you haven’t implemented this before, you might find our Single-page Applications (SPA) with API architecture scenario useful. It covers a different scenario, but it explains how to configure Auth0, how to call an API from a SPA, and how to implement API validations. It comes with a sample that uses Angular 2 and Node.js. We also offer a Mobile Applications with API variation (the sample uses Android and Node.js).