Authentication for REST API

Owned by Jan Panoušek
Last updated: Aug 03, 2023 by Stephen Cotton

To get access to server resources, the user must be authenticated. The API itself has only one version, however the authentication part can be called in two versions – version 1 and version 2.

While  the name "version 2" suggests that this version is "newer" or "better", it is not. It is simply different. So it is absolutely fine to use version 1. The default user interface, the Excel client and many other systems rely on and use version 1 authentication.

  • In version 1 authentication credential is always a so called "JWT" (JSON Web Token).
    • The token can be either sent as a HTTP header or as a Cookie.
    • The token has an encoded expiration timestamp.
    • Such a JWT token is automatically issued (as a Cookie) when an API call with user/pass authentication header is called. It is highly recommended to use the JWT for subsequent calls and not user/pass on every API call.
    • Once the JWT nears its expiry, the server automatically re-issues (again as an updated Cookie) a new JWT token value. The client should then replace the token on their end. Cookie-aware clients (such as browsers) do that automatically.
    • Special API endpoints can issue long-lived JWT e.g. for integration purposes.
    • JWT tokens can be invalidated on a per user basis by changing the user's password.
    • JWT are also issued at the end of successful SAML login flows (i.e. to remove the need for presenting a user/pass credential at the beginning of the flow).
  • In version 2 authentication is strictly done by:
    • So called "Auth-Tokens" that have a limited lifetime (which is not auto-extended as for session cookies).

    • Standard HTTP basic auth-headers or session cookies are banned. 

    • For details see the REST API documentation.

Flow in version 1: 

  1. Your first request needs to have the basic auth header (user/pass).
  2. Then you automatically get a JWT token as a cookie back as part of the response.
  3. ​This cookie can (and should) be used for subsequent requests.
  4. ​Once the JWT nears expiration, the backend will automatically issue a new cookie with a new JWT. 
    So an HTTP client with automatic cookie handling (like a browser) does not need to do anything. All magically works behind the scenes.

For other clients (curl, custom code etc.) this need to be more manual, but along the same lines.

Basic Authorization

This authorization method is intended only for simple uses cases, not for production, since it is based on adding a header to any request sent to the server.

Authorization: Basic <Base64-encoded user data>

Data that will be Base64-encoded should have the following format:

<partition name>/<user name>:<password>


Example

Authorization of a dummy user on the 'pricefx-qa' partition

  • Partition name: pricefx-qa

  • User name: user1

  • Password: pass_123

Data to encode: pricefx-qa/user1:pass_123

Base64 encoding result: cHJpY2VmeC1xYS91c2VyMTpwYXNzXzEyMw==

The authorization header that will be added to the request to get a response should then be as follows:

Authorization: Basic cHJpY2VmeC1xYS91c2VyMTpwYXNzXzEyMw==

Password verification is intentionally very CPU intensive to mitigate brute-force attacks. For optimal API speeds, use JWTs in API requests where possible


Basic Authorization in Postman

If you are using Postman to call Pricefx REST API, you will resolve authorization directly in the app's UI.

  1. On the Authorization tab, select Basic Auth from the Type drop-down list.
  2. As Username, enter <partitionName>/<yourUserName>.
  3. Enter your password for the partition.


Authorization Using the X-PriceFx-jwt Cookie

The preferred authentication method for requests sent to the Pricefx backend is the X-PriceFx-jwt cookie file. You can get this file by logging in to the system. This can be done by sending a request to the server via the endpoint POST <partition name>/login/extended.

For example, for the partition pricefx-qa on the QA server the address will be:

<base address>/<partition name>/login/extended
https://qa.pricefx.eu/pricefx/pricefx-qa/login/extended

You must add the Basic authorization header to the request. In the server response, you will find the X-PriceFx-jwt cookie file.

This method should be preferred whenever possible for better performance. As the basic authorization is for security reasons much more time consuming, using the cookie file can save 0.5 seconds on each request.

Found an issue in documentation? Write to us.