API Reference

Managing User Tokens

User Tokens are used to access the Pillars APIs by a particular user.

Creating a User Token

There are two methods available for generatint a user token.

1. User Tokens can be generated by making a call to /Authentication

curl --request GET \
     --url 'https://api.pillarshub.com/Authentication?username={username}&password={password}' \
     --header 'accept: application/json'

If the user does not exist or the credentials are invalid, a 401 Unauthorized will be returned.

An environment can be passed if the required environment is known.

2. User Tokens can be generated by making a call to /Authentication/UserToken

curl --request GET \
     --url 'https://api.pillarshub.com/Authentication/UserToken?username={username}' \
     --header 'accept: application/json'

If the user does not exist, a 404 Not Found will be returned.

An Access Token must be passed as part of the authentication header.

📘

User Tokens are Exclusive to Customer-Associated Users

User Tokens within our system are exclusively designed for customers and their associated users. Please be aware that User Tokens cannot be generated for administrative users.

Refresh a User Token

Refreshing a User Token becomes necessary for two primary reasons:

  1. User Token Expiration:

    The User Token is expiring, requiring renewal to maintain authentication.

  2. Update User Token's Environment:

    The environment associated with the User Token needs updating.

To refresh a User Token, initiate a call to the /Authentication/refresh/{token}

curl --request GET \
     --url https://api.commissionsportal.com/Authentication/refresh/token \
     --header 'accept: application/json'

When refreshing a User Token and the environment parameter is not provided, the newly generated token will retain the same environment as the original token. This ensures continuity in the environment associated with the refreshed User Token.

Managing Environments in User Tokens

In the Pillars API ecosystem, most operations necessitate the presence of a token with an assigned environment. To streamline this process, it is advisable to assign the environment when initially creating a User Token. However, in cases where the environment is unknown, a temporary User Token can be generated to retrieve a list of available environments.

Follow these steps to for generating a User Token when the environment is not known:

  1. Create a Temporary User Token

    When creating a User Token initially, omit the environment parameter. This action generates a User Token without an assigned environment. Refer to the "Creating a User Token" section for detailed instructions.

  2. Retrieve Available Environments

    Utilize the generated temporary User Token to make a call to the Authentication/token/{token}/Environments endpoint. This API call will provide a list of available environments associated with your Pillars system.

  3. Refresh the User Token

    After obtaining the list of available environments, refresh the User Token, this time including the desired Environment Id. By doing so, a new User Token specifically assigned to the chosen environment will be generated.

  4. Ready for Use

    The refreshed User Token, now associated with the designated environment, is ready for use in subsequent API calls. Ensure that you incorporate this updated User Token to access Pillars API functionalities within the specified environment.