Authenticating with iQmetrix APIs

This guide describes how to obtain an Access Token, a serialized security object required to access iQmetrix APIs.

Prerequisites

To use this guide, first complete the following steps:

You must have your onboarding package from iQmetrix, which includes your client_id, client_secret and the username and password for the user(s) you will be using to access iQmetrix APIs.

Steps

Step 1 - Obtaining an Access Token

The first step is to exchange your credentials for a short-lived access token using Obtaining an Access Token and the following parameters:

grant_type - Use password
client_id - Provided in Onboarding Package
client_secret - Provided in Onboarding Package
username - Provided in Onboarding Package
password - Provided in Onboarding Package

Example Request (cURL)

curl -X POST \
  https://accountsrc.iqmetrix.net/v1/oauth2/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&client_id=PROVIDEDCLIENTID&client_secret=PROVIDEDSECRET&username=EMAIL&password=PASSWORD'

Example Response

HTTP 200
{
    "access_token": "b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz",
    "expires_in": 43199,
    "refresh_token": "FOPAB0K3eshQjrJW4mt6FbWF3OwDJL7CGdZX"
}

Step 2 - Exchange Token

The Access Token from Step 1 will expire in a short period of time. Instead of getting a new Access Token every time it expires, you should exchange a refresh token for a fresh access token.

Definition: A Refresh Token is a special kind of token used to 'reauthenticate' without needing to enter credentials when the Access Token expires. Just like how apps in your phone are 'always logged in' - behind the scenes, they are issuing refresh tokens. You can request new Access Tokens until the Refresh Token is blacklisted. For this reason, you must store Refresh Tokens securely, because they allow a user to remain authenticated forever.

Exchange a refresh token for a fresh access token using Obtaining an Access Token and the following parameters:

grant_type - Use refresh_token
client_id - Provided in Onboarding Package
client_secret - Provided in Onboarding Package
refresh_token - The refresh_token from the first step, in this case FOPAB0K3eshQjrJW4mt6FbWF3OwDJL7CGdZX

Example Request (cURL)

curl -X POST \
  https://accountsrc.iqmetrix.net/v1/oauth2/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=PROVIDEDCLIENTID&client_secret=PROVIDEDSECRET&refresh_token=FOPAB0K3eshQjrJW4mt6FbWF3OwDJL7CGdZX'

Example Response

HTTP 200
{
    "access_token": "6LxbJGJBgmxV93Pe5iHy7hVXxenGaWf7ugdIlzb4HB23gZ0HL0jshjJfXuKz2ltK827SxjwphqLtjZBtwrOoUmw8tgIKZr6op2Ak",
    "expires_in": 43199,
    "refresh_token": "OdAjnHCu0o8nuU7nDqxUpox1gctfQnRU5NhwyrEY"
}

Step 3 - Use the Token

The token (access_token) is placed in the Authorization header of requests to iQmetrix APIs, prefixed by the word Bearer.

Example Request (cURL)

curl -X GET \
  https://entitymanagerrc.iqmetrix.net/v1/Manufacturers \
  -H 'Authorization: Bearer 6LxbJGJBgmxV93Pe5iHy7hVXxenGaWf7ugdIlzb4HB23gZ0HL0jshjJfXuKz2ltK827SxjwphqLtjZBtwrOoUmw8tgIKZr6op2Ak'

Next Steps

Now that you have created a token, you may be interested in:

Getting Information About an Access Token