After registering an application in EmpowerID, the next step for working with the API is to use the credentials generated for that application—which consists of the API Key, the Client ID and the Client Secret—to get an access token. The access token is what authorizes resource API calls. The resources that can be manipulated vary, depending on the Access Levels associated with the application user. Access tokens can be issued as OAuth 2.0 tokens or JWT tokens. In this topic, we demonstrate getting an OAuth 2.0 token.

The default expiration time for JWT and access tokens is 3600 seconds. You can change this value in the Token Expiration (in seconds) field on the application. To do so:

In the Navigation Sidebar, expand Admin, then SSO Connections, and click OAuth.
Open the Application Details for the application and click the Edit button.
On the General tab, you can find the setting in the OAuth Application Details section.

To get an access token

To get an access token, you need to make a POST request to https://{FQDN_Of_Your_EmpowerID_Web_Server}/oauth/v2/token with the following header and data value pairs:

Headers

Key	Value
X-EmpowerID-API-Key	The API key for the OAuth application you created.
Authorization	This is the Basic authentication scheme for the EmpowerID Person requesting the access token. To use this scheme, you set the value to the base-64 encoded value of the person's username and password. To get this value, you can visit one of many websites that provide this service, write your own code, or use a REST client like Postman.
Content-Type	application/json

Request Data

Request data is sent to the API in JSON format.

{ 
  "client_id": "{The Client ID of the OAuth app you created above}",
  "client_secret": "{The Client Secret of the OAuth app you created above}",
  "redirect_uri": "{The Redirect URI of the OAuth app you created above}",
  "grant_type": "password"
}

Response

If the request is successful, you should receive a JSON response that looks similar to the following:

{
   "access_token": "WER1RFdjUVF1OE52ekdWZjJIQjMzSHVqcERQT0p5c...aZW",
   "token_type": "Bearer",
   "expires_in": 3600,
   "refresh_token": "YnQrRHhuyYmNidzY3MTFSVnE1Q1BLN1RuZ1liOH...WQ==",
   "id_token": "null",
   "error": "",
   "error_description": "null"
}

Code Examples

cURL

Be sure to use double quotes unless you are making the request from a non-Windows OS.

curl "https://{FQDN_Of_Your_EmpowerID_Web_Server}/oauth/v2/token" \
-H "X-EmpowerID-API-Key: {Your_API_Key} \
-H "Authorization: Basic {base64_encoded_value_of_the_EmpowerID_Person_username_and_password}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&client_id={Your_Client_ID}&client_secret={Your_Client_Secret}&redirect_uri=
https://{FQDN_Of_Your_EmpowerID_Web_Server}/webidpforms/oauth/v2"

Ajax

var auth = btoa("EmpowerID_Person_Username:EmpowerID_Person_Password")
$.ajax({
  url: "https://{FQDN_Of_Your_EmpowerID_Web_Server}/oauth/v2/token",
  type: "POST",

  headers: {
    "X-EmpowerID-API-Key": "1a9e18d5-7ec8-4214-b4e7-23b550c9c6ba",
    "Content-Type": "application/json",
    "Authorization": "Basic " + auth    
  },

  data: JSON.stringify({
  "client_id": "Your_Client_ID", 
  "client_secret": "Your_Client_Secret", 
  "redirect_uri": "https://{FQDN_Of_Your_EmpowerID_Web_Server}/webidpforms/oauth/v2",  
  "grant_type": "password"
  })
});

Postman Example

If you'd rather manage your API calls with a more graphically oriented tool, there are a number of browser extension applications that you can use, such as Postman for Chrome and RESTClient for Firefox. In this topic, we use Postman.

Open the Postman app on your machine.
In Postman, open a new tab, select POST as the HTTP method and enter https://{FQDN_Of_Your_EmpowerID_Web_Server}/oauth/v2/token.
Click the Headers tab add the above mentioned key/value pairs.

Click the Body tab, select raw and then add the below JSON:

{ 
   "client_id": "{Your_Client_ID}", 
   "client_secret": "{Your_Client_Secret}",
   "redirect_uri": "https://{FQDN_Of_Your_EmpowerID_Web_Server}/webidpforms/oauth/v2",  
   "grant_type": "password" 
}

Click Send.

If the request is successful, you should receive a JSON response that looks similar to the following:

Now that you have the access token for your application, you can start working with the API as demonstrated in the Creating a Person topic.

On this page

Browser not supported