Authentification and JWT Token

To explore further than the root endpoint /, you will need a valid account.

Generally speaking, the Crossing Minds API uses the JWT standard to authenticate the requests. The Authentication documentation explains these mechanisms in more detail.

Before creating any database or receiving any recommendation, you will need to authenticate using the root account. Let’s assume the correct values are found in the following environment variables:

‍

Title

Copied to clipboard!

$ export XMINDS_API_ROOT_EMAIL="your.root@your.email.com"
export XMINDS_API_ROOT_PWD="y0urAP1key"

$ export XMINDS_API_ROOT_EMAIL="your.root@your.email.com"
export XMINDS_API_ROOT_PWD="y0urAP1key"

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' PHP

$curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' JAVA

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' NODE

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' GO

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' NET

‍

Your first JWT token will be obtained from the endpoint POST login/individual/ using the root email/password combination.

‍

Title

Copied to clipboard!

$ curl https://api.crossingminds.com/login/individual/ -s \
  -H "Content-Type: application/json" \
  -d '{"email": "'"$XMINDS_API_ROOT_EMAIL"'", "password": "'"$XMINDS_API_ROOT_PWD"'"}' \
  | jq -r

$ curl https://api.crossingminds.com/login/individual/ -s \
  -H "Content-Type: application/json" \
  -d '{"email": "'"$XMINDS_API_ROOT_EMAIL"'", "password": "'"$XMINDS_API_ROOT_PWD"'"}' \
  | jq -r

$ curl https://api.crossingminds.com/login/individual/ -s \
  -H "Content-Type: application/json" \
  -d '{"email": "'"$XMINDS_API_ROOT_EMAIL"'", "password": "'"$XMINDS_API_ROOT_PWD"'"}' \
  | jq -r

$curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' JAVA

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' NODE

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' GO

$ curl https://api.crossingminds.com/recommendation/users/111/items/?amt=3 -s \
  -H "Authorization: Bearer $JWT_TOKEN" \
  | jq -r '.items_id' NET

‍

Response

Copied to clipboard!

{
  "token": "eyJ0eXAiOiJ..."
}

‍

Once you get a token, you won’t need to use a password to authenticate.

In the Authentication documentation you may also read about refresh tokens, which provides a mechanism to renew the short-lived JWT token automatically without having to enter your password again. This is particularly helpful to implement frontend clients without having to expose your API key publicly.

Using JWT and Refresh Tokens

Authenticating Requests with JWT

Once you get a JWT, you can use it in the Authorization HTTP header (see RFC6750), using the syntax:

Authorization: Bearer <JWT_TOKEN>

If you are using an official client, this is done automatically.

Renewing the JWT with a Refresh Token

For security reasons, the JWT is short lived. In order to automatically re-login when the token expires, you can use the refresh token.

This is done by calling POST login/refresh-token/, which returns a new short-lived JWT, and eventually a new refresh token as well if it was about to expire.

You can also change the selected database when renewing a JWT.

If you are using an official client, this is also done automatically.

New Account Creation

You may want to create multiple accounts instead of using only the root account. For instance to create accounts with less permissive roles than root. The necessary steps are as follows:

use POST accounts/individual/ or POST accounts/service/ from an account with root or manager role
for individual accounts, verify the email address using GET accounts/verify/ to enter the code that has been sent to your email address
the new account can be used to login and select your database with POST login/individual/ or POST login/service/ as before

‍

Back

Learn how to use Crossing Minds Dashboard to get recommendations for your business needs