Authentication

The ItemPath API uses token-based authentication in order to validate user access. This is OAuth 2 standard.

In order to make requests through the API, you must include an access token in the header of the API request:

Access & Refresh Tokens

In order to receive an access token, you must first login through the /api/users/login endpoint with your username, password passed in the body.

curl --location --request POST 'https://localhost/api/users/login' \--header 'Content-Type: application/json' \--data-raw '{ "username": "username", "password": "password"}'

The returned response should be something like:

"login": true,
"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYzMTQwNjE4MSwianRpIjoiMmE1NWZlMmMtMjg1Ny00OTJmLTkyMzEtZTlkOTUzZDFhNzZhIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoibWdvcmRvbiIsIm5iZiI6MTYzMTQwNjE4MSwiZXhwIjoxNjMxNDA3MDgxfQ.65uARe8bQuNXHqVk2ykYxe-VeStQChY_Z5mEZ3Sqhec",
"refreshToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYzMTQwNjE4MSwianRpIjoiZGNjZTE0NGYtZTI0Ny00NWViLWIwNzQtYzk5YTUzNWI1YjYzIiwidHlwZSI6InJlZnJlc2giLCJpZGVudGl0eSI6Im1nb3Jkb24iLCJuYmYiOjE2MzE0MDYxODEsImV4cCI6MTYzMzk5ODE4MX0.ZKxct86KfVMQ8HDyRVeE6o2_SifF-t2sH5XCO7PV7x4"

Save the returned access token and refresh token.

When making an API request, include the access token in an authorization header of type Bearer.

'Authorization: Bearer [access token]'

curl --location --request GET 'https://localhost/api/stations'
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYzMTQwNjE4MSwianRpIjoiMmE1NWZlMmMtMjg1Ny00OTJmLTkyMzEtZTlkOTUzZDFhNzZhIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoibWdvcmRvbiIsIm5iZiI6MTYzMTQwNjE4MSwiZXhwIjoxNjMxNDA3MDgxfQ.65uARe8bQuNXHqVk2ykYxe-VeStQChY_Z5mEZ3Sqhec'

After 15 minutes, the access token will have expired and a new one will need to be generated. To do this, access the /api/users/refresh endpoint. Include the Bearer Authorization header, but instead of using the access token, include the refresh token given to you when you first accessed the login endpoint. A new access token will be returned to you in the body. You can now use this token in the authorization header when making API requests.

After 30 days, the refresh token will expire. In order to generate a new refresh token, you must go through the login process again(as described above).

Application Tokens

If you would prefer to avoid having to refresh an expired token, you can generate an application token — a non-expiring access token. These can only be created by users with the type set to "application." Note: For security, we recommend Cloud customers stick with using the refresh token.

To create this token, access the /api/users/application-token endpoint using your refresh token as the Bearer authorization header.

curl --location --request POST 'https://localhost/api/users/application-token'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYyOTQwMjYxMCwianRpIjoiZGQ2ZjFiYTctOTU4Yi00MTJmLWJkNjktOTJkZGUwMTE2NDczIiwidHlwZSI6InJlZnJlc2giLCJpZGVudGl0eSI6Im1nb3Jkb24iLCJuYmYiOjE2Mjk0MDI2MTAsImV4cCI6MTYzMTk5NDYxMH0.bUDN3lswIp5m-YouXVbbHPiizLrelOE_AZ7lB_HUX2k'

In the body of the response will be the application token:"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYzMTQwNjUxMCwianRpIjoiN2Q4YTAwZmEtNGZiOC00MmUyLWE1MGQtMzZkNWQ3Y2M1YTBmIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoibWdvcmRvbiIsIm5iZiI6MTYzMTQwNjUxMH0.T_dYn0Mc4hjDo2WyQ_e3zMEOYmQiBWVzlyW_gQaE62c"

Single Sign-On

In addition to logging in with a secure ItemPath user, it's also possible to use SSO. Check out this guide to see what's required for Azure MSAL SSO configuration.