EnglishFrançaisDevelopers

Authentication

105The Quable PIM API uses bearer authentication. This allows the Quable PIM API to verify your identity, and send you a unique access token.

You must have a user account to use the Quable PIM API. This account is used to request/receive a generic or user-based authorization token for each session.

To get started using the Quable PIM API, follow these steps:

  1. Create a Quable PIM user account.
  2. Log into the API and request an authorization token.
  3. Receive the Response from the API with the token.

👍

Access tokens are shared between API v4 and API v5, so you don't need specific versions per API.

Accepted Tokens

Two types of tokens can be used with the Quable PIM API.

Generic token

This is a global token. You must have a user account in order to access the System > API token menu, however the token is not based on it (e.g., User-based token) and you don't need to request a new token at each job execution.

These tokens can be directly used with both API v4 and v5.

🚧

Generic tokens must be requested from and configured by the Quable PIM service desk.

User-based token

You must have a user account to use the Quable PIM API. This account is used to request/receive a new token for each job execution.

If you use a user-based token, it must be unique. This means that when a token request is made, the previoususer-based token is invalidated. Therefore, it's important to have a specific user account for the type of job and to take into account this constraint.

Token Lifetime

Access tokens are valid for a single session. Token requests for an account already in use will invalidate any previous tokens. By default, a session lasts for 30 days.

Creating a User Account

❗️

Attention

There are no limitations or restrictions on API user accounts. They have full access to all data.

Quable PIM user accounts are created by Quable PIM administrators (or users with sufficient permission to create a user) via the Quable PIM interface (Administration > Users).

The Username and Password for the account should be used for a unique session. Each new authentication request will remove previous access tokens. For example, if a single user account is used for both the interface and for the API, logging into one will invalidate the token of the other.

👍

To ensure that the user account for the API doesn't impact the number of users defined in your Quable PIM contract, prefix the Username with "api_". This also simplifies identifiying who and where specific actions were performed.

Login and Token Request

To retrieve an access token, this call must be made to the API's api_1.php/sessions endpoint specifying your Quable PIM instance and user account information: 

import requests
import json

url = "https://{{YOUR-PIM}}.quable.com/api_1.php/sessions"

payload = json.dumps({
  "signin": {
    "username": "{{YOUR-API-USERNAME}}",
    "password": "{{YOUR-API-PASSWORD}}"
  }
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

👍

Be sure to change the address for your Quable PIM instance, username, and password.

Using a Token

Once you've retrieved the token (generic or user-based), it should be used as a Bearer Access Token. The examples in this guide use these tokens and will be shown in Python examples as parameter:

headers = {
  'Authorization': 'Bearer 94fa500c0fbd121480e46690e733453f'
}

API Response

Once the API has verified your identity and access rights, it will send a response. The response can be read in two sections:

  • the HTTP Header - Indicates the success or failure of the request with a response code and message.
  • the Response Body - If the request is successful, the response body includes the requested information. Otherwise the response body is empty.

The following is an example of response to a successful request.

HTTP Header

201

Response Body

The response returns an array containinging multiple pieces of information. The access token can be found as the oauth.access_token value.

{
  ...,
  "oauth":{
    "access_token": "94fa500c0fbd121480e46690e733453f",
    "expires_in": 3600,
    "refresh_token": null
  }
}