API Authentication

The authentication scheme used for the API is based on using JSON Web Tokens (JWT) when authenticating containing permissions that map to individual REST resource of the API.

Authentication

Authenticating with the API starts by generating an API Token for your PriceShape account. This is done by going to the API page under account settings in the PriceShape portal and clicking on the Generate new token button.

Note: be sure to save the API token somewhere safe once generated, as you won't be able to view it again afterwards.

Once you have an API token, all you need to do is add it to your headers, Authorization: Bearer <api-token>, in every request you make the API:

Remember to also include the version header X-API-Version and any other headers that might be required such as Content-Type.

To learn more about JSON Web Tokens go to https://www.jwt.io/.

JSON Web Token content

If you decode and inspect the content of the JWT you see will something like the following:

{
  "id": "4069107995a84350b48b3cd079cb4d98",
  "account": "6201ab9c3e2348ae8072c608cab91e29",
  "iss": "priceshape",
  "aud": "priceshape-api",
  "iat": 1769601807,
  "exp": 1800955000,
  "permissions": {
    "feeds": "read",
    "products": "write"
  }
}

where:

id unique ID of the token.

account unique ID of the account.

iss is the issuer of the token.

aud is the audience of the token.

iat is the 'issued at' time in POSIX time.

exp is the expiration time in POSIX time.

permissions is the hardcoded set of permissions assigned to the token. Futher explained in the 'Authorization' section below.

Authorization

The permission model of the API works by mapping each REST resource to a permission scope (none, read, or write). For example, if an API token is able to read feed data and able to update product data it will have the following permissions set inside the JWT:

{
  "feeds": "read",
  "products": "write"
}

Any given permission covers all actions related to that resource unless explicitly stated otherwise, i.e. having write permission to products allows GET, POST, PUT and DELETE requests to all of the endpoints:

/feeds/:feedId/products/
/feeds/:feedId/products/:upi
/products

while read permission to feeds allows GET requests to the endpoints:

/feeds
/feeds/:feedId

Note that having read access to feeds does not give access to its related subresource products by default.

Authentication#

JSON Web Token content#

Authorization#

Authentication

JSON Web Token content

Authorization