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 withfrontend
role, providing thefrontend_user_id
of the specific user. This returns a JWT and a refresh token that are valid only for resources belonging to this useryour 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:
use
POST accounts/individual/
orPOST accounts/service/
from an account withroot
ormanager
rolefor individual accounts, verify the email address using
GET accounts/verify/
to enter the code that has been sent to your email addressthe new account can be used to login and select your database with
POST login/individual/
orPOST login/service/
as before