Authentication

This page documents the authentication flow such as using short-lived JWT tokens, refresh tokens, and creating new accounts.

Accounts and Roles

Accounts Types

There are two different account types on the Crossing Minds API, individual accounts and service accounts.

Individual Accounts

Individual accounts are intended for real persons. These accounts are identified by an email.

The email has to be verified, so we can safely use it to send a reset password email.

Service Accounts

Service accounts are intended for backend or frontend scripts. These accounts are identified by a service name.

They are simpler to create since no email needs to be validated, but no reset password email can be sent.

Roles

There are four different roles you can assign to individual or service accounts.

Root

The root role has full permissions.

This unique “system role” is automatically assigned to the root account of your organization.

Manager

The manager role has full permissions.

Backend

The backend role has with full permissions only for endpoints under the “database” resource. For instance this role cannot create or delete accounts nor databases.

Frontend

The frontend role is used to limit permissions to only read&write on resources belonging to a specific user of your app, and getting recommendation for this specific user.

Specifying the user is done during login and not during account creation. Therefore you don’t have to create one account with frontend role for each of your user.

See below for more details on authenticating with a frontend user.

Login to Get a JWT

Login and Selecting a Database

The first step to use the Crossing Minds API is to call POST login/individual/ (resp. POST login/service/) to get a short-lived JSON Web Token (JWT) for your database.

You will need provide your email (resp. service name), password and the ID of your database. Upon successful request, the API will return a JWT token and a refresh token.

You can change the database you selected by calling POST login/individual/ (resp. POST login/service/) again, and using the new JWT token.

Login and Specifying a Frontend User

If you plan to use the Crossing Minds API directly from your frontend application (e.g. web or mobile), you should use an account with the frontend role. This is to ensure that the credentials exposed in the frontend application do not grant permissions beyond what is necessary.

The steps to authenticate your frontend user are as follows:

  • your user logs-in with your app, therefore calling the login endpoint of your backend

  • your backend calls POST login/service/ on an account with frontend role, providing the frontend_user_id of the specific user. This returns a JWT and a refresh token that are valid only for resources belonging to this user

  • your backend sends the JWT and the refresh token to your frontend application

  • your frontend application can use the JWT to manipulate ratings and get recommendations, but cannot see other users’ ratings

  • when the JWT expires your frontend application can use the refresh token to get a new JWT, without having to expose your account password

Login Without Selecting a Database

The root account can also use the endpoint POST login/root/, which is equivalent to the previous endpoint, except that no database is selected and no refresh token will be created.

This is particularly useful to create your first database.

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.

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: