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.

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.

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

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

To grant or remove scopes from the registered Auth0 Management API, select the Machine to Machine Applications view:

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.

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.

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}'

var client = new RestClient("https://{yourDomain}/api/v2/users/%7BuserId%7D");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer {yourAccessToken}");
IRestResponse response = client.Execute(request);

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://{yourDomain}/api/v2/users/%7BuserId%7D"

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

	req.Header.Add("authorization", "Bearer {yourAccessToken}")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users/%7BuserId%7D")
  .header("authorization", "Bearer {yourAccessToken}")
  .asString();

var axios = require("axios").default;

var options = {
  method: 'GET',
  url: 'https://{yourDomain}/api/v2/users/%7BuserId%7D',
  headers: {authorization: 'Bearer {yourAccessToken}'}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

#import <Foundation/Foundation.h>

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

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/%7BuserId%7D"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[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, [
  CURLOPT_URL => "https://{yourDomain}/api/v2/users/%7BuserId%7D",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: Bearer {yourAccessToken}"
  ],
]);

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

curl_close($curl);

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

import http.client

conn = http.client.HTTPSConnection("")

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

conn.request("GET", "/{yourDomain}/api/v2/users/%7BuserId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

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

url = URI("https://{yourDomain}/api/v2/users/%7BuserId%7D")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer {yourAccessToken}'

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

import Foundation

let headers = ["authorization": "Bearer {yourAccessToken}"]

let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/%7BuserId%7D")! 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) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

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.

You can find the Access Token used to call the IdP's API within the user's identities array: user.identities[0].access_token.

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.

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 Client Secret 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.

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