Call an Identity Provider API

Call an Identity Provider API

Once you successfully authenticate a user with an external Identity Provider (IdP), such as Facebook or GitHub, the IdP often includes an Access Token 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. To see your options 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.

Auth0, for security and compliance reasons, does not send this token to your app as part of the user profile. In order to get it you will have to access the Auth0 Management API and retrieve the full user's profile.

The steps to follow are:

  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.

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 API.

To do so, go to Dashboard > APIs > Auth0 Management API > API Explorer and click Create & Authorize a Test Application.

This will create a new application and grant all scopes of the Management API. This 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 have at least one authorized application already. In this case you can either update the scopes of an existing application and use that, or create a new one following these steps:

  1. Go to Dashboard > Applications
  2. Click + Create Application, select Machine to Machine Applications and click Create
  3. At the Select an API dropdown select Auth0 Management API
  4. Click Navigate to the API and Authorize
  5. Set the toggle to Authorized and enable the required scopes

It is recommended, for security reasons, that you only assign 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.

You can grant or remove scopes from an application, at the Dashboard > APIs > Auth0 Management API > Machine to Machine Applications tab.

Edit the scopes granted to the Application

You are now done with the configuration part, and you are ready to get your Management API token.

To do so, go to the Test tab. There you can find ready-to-use snippets that you can use to get a token.

Pick your application using the dropdown at the top, and choose your language of preference for the snippet.

Copy and run the snippet. Extract the access_token property from the response. This is what you will use to access the Management API.

More info on the snippets

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. For more information on the flow, refer to Client Credentials Flow.

Token expiration

The token you received has, by default, an expiration time of 24 hours (86400 seconds). To change this, update the Token Expiration (Seconds) field, at the Settings tab and save your changes. The next token you generate will use the updated expiration time. The maximum value you can set is 2592000 seconds (30 days) however our recommendation is to keep the default value.

Security warning

These tokens cannot be revoked. To minimize the 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. You can find a sample implementation in Python here.

Step 2: Get the full User Profile

Using the Access Token you got in the previous section, call the Get a User endpoint of the Management API, in order to get a user's profile:

curl --request GET \
  --url 'https://YOUR_DOMAIN/api/v2/users/USER_ID' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/users/USER_ID");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN");
IRestResponse response = client.Execute(request);
package main

import (

func main() {

	url := "https://YOUR_DOMAIN/api/v2/users/USER_ID"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)


HttpResponse<String> response = Unirest.get("https://YOUR_DOMAIN/api/v2/users/USER_ID")
  .header("authorization", "Bearer YOUR_ACCESS_TOKEN")
var request = require("request");

var options = {
  method: 'GET',
  url: 'https://YOUR_DOMAIN/api/v2/users/USER_ID',
  headers: {authorization: 'Bearer YOUR_ACCESS_TOKEN'}

request(options, function (error, response, body) {
  if (error) throw new Error(error);

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/api/v2/users/USER_ID"]
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
[dataTask resume];
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/users/USER_ID",
    "authorization: Bearer YOUR_ACCESS_TOKEN"

$response = curl_exec($curl);
$err = curl_error($curl);


if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
import http.client

conn = http.client.HTTPSConnection("")

headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN" }

conn.request("GET", "/YOUR_DOMAIN/api/v2/users/USER_ID", headers=headers)

res = conn.getresponse()
data =

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://YOUR_DOMAIN/api/v2/users/USER_ID")

http =, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request =
request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN'

response = http.request(request)
puts response.read_body
import Foundation

let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN"]

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/api/v2/users/USER_ID")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
  } else {
    let httpResponse = response as? HTTPURLResponse


Replace these values:

  • USER_ID: The ID of the user for whom you want to call the IdP's API.
  • YOUR_ACCESS_TOKEN: The token you got from the previous step.

Where do I find the User ID?

  • For testing purposes, you can find a user ID at Dashboard > Users. Select a user and copy the value of the user_id field.
  • For your implementation, you can either extract this information from the ID Token (get the value of the claim sub), or call the /userinfo endpoint of the Authentication API (get the value of the response property user_id).

Step 3: Extract the IdP Access Token

Within the user's identities array, there will be an Access Token that you can extract and use to make calls to the IdP's API: user.identities[0].access_token.

For certain Identity Providers, Auth0 will 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, Azure AD. For more information, refer to Identity Provider Access Tokens.

In most cases, the user will only have one identity, but if you have used the account linking feature, there may be more.

In this sample response we can see that our user had only one identity: google-oauth2.

  "email": "",
  "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": "",
  "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.

Make sure that you don't expose the IdP tokens to your client-side application! If your application is public refer to the frontend section of this article.

For more information on how to request specific scopes for an Identity Provider Access Token, please see 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.

As you might have read earlier in this article, the process for calling IdP APIs from a backend process includes the following steps:

  1. Get an Access Token in order to access the Auth0 Management API
  2. Use said token to retrieve the user's full profile from the Auth0 Management API
  3. Extract the IdP's Access Token from the user's full profile, and use it to call the IdP's API

You cannot follow the same process from a frontend app because it's a public application that cannot hold credentials securely. The credential we are referring to, is the machine to machine application's secret which you use to make the call to /oauth/token, at the first step of the process.

SPA's code can be viewed and altered and native/mobile apps can be decompiled and inspected. As such, they cannot be trusted to hold sensitive information like secret keys or passwords.

There are some alternatives you can use.

Option 1: Build a proxy

You can build a process in your backend and expose it to your application as an API.

The backend process will implement the steps of the backend section. 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 respective flow for your case:

Show me how to do it

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

Option 2: Use webtasks

Only tenants created prior to 17 July 2018 have access to and the Webtask CLI. If you are an enterprise customer with a newer tenant, please contact your account representative to request access. Other requests can be made through the Auth0 Contact Form and will be evaluated on a case-by-case basis.

If you don't have a backend server, and you don't want to set up one, then you can leverage serverless technology, using webtasks.

Webtasks are the Auth0 way to create HTTP endpoints with Node.js and access them from anywhere. It's a way to safely execute server-side logic, when you do not have a backend. They come with a command line tool and an editor. For more info, see the documentation.

In this scenario, you will create a webtask and implement the steps of the backend section. Then the webtask will call the IdP's API so the Access Token is never exposed to your public application.

Your application will invoke the webtask with a simple HTTP request and manipulate the response appropriately (for example, render the user's GitHub repositories in the UI).

You can find a sample in this GitHub repository. Review carefully before you use it since this is not officially maintained by Auth0 and could be outdated.