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:

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:

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:

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: