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 is used to receive links with a code to set or reset the password.

Service Accounts

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

Service accounts use keys instead of passwords to login. The same service account can have multiple keys.

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 the Frontend Authentication Flow 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 account email (resp. service name) and password (resp. key), and optionally the name or ID of your database. Upon successful request, the API will return a JWT token and a refresh token for this account and this database.

Most endpoints require a database name or ID to be set, but individuals can still login without database which is particularly useful to create your first database.

When login using a database, it is preferable to use the database name instead of the database ID because the database ID is an abstract value that is not easily interpretable by humans.

You can change the database you selected by calling POST login/individual/ (resp. POST login/service/) again, or when renewing the JWT from the refresh 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.

Lenient permissions

Since the permissions granted to an account with frontend role are very limited, you may choose to simply embed the key of this account in your frontend app.

Doing so greatly simplifies the authentication flow as your frontend can directly get recommendations from the Crossing Minds API.

The downsides are that a malicious agent can:

  • request recommendations for any user ID or session ID,

  • create or delete ratings or interactions for any user ID or session ID.

Note that recommendations may indirectly leak sensitive information about your users, such as recorded interactions with your items. Therefore using this process can be problematic in the case where a malicious agent can scan all existing user ID or session ID; but is less concerning when these IDs are not public and randomly generated with enough entropy (e.g. UUIDv4).

Strict permissions

When the above downsides are not compatible with your use case, you need to leverage your backend to authenticate requests. Then you can use the following steps to create frontend tokens with strict permissions:

  • Your user enters your app, calling the authentication endpoint of your backend. If your user is logged-in the backend retrieves their user ID, if your user is anonymous the backend retrieves or generates an anonymous session ID.

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

  • 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’ recommendations. The user_id or session_id parameters of the endpoints will be set by default using the value provided. In endpoints where the user or session ID is used as URL parameter, it is possible to replace it with the ~me keyword to use the value provided. For instance GET recommendation/users/~me/items/.

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

  • If an anonymous session ends up logging-in, your backend should call POST login/service/ providing both the frontend_user_id and frontend_session_id at the same time. This way the Crossing Minds API will resolve the anonymous session to the user.

Login through Single Sign-On (SSO)

The API supports logging in via SSO through the Security Assertion Markup Language (SAML) standard, so the endpoint POST login/sso/saml/sp/ is available for that to start the authentication flow through OKTA as Identity Provider (see OKTA).

After a successful login, a refresh token will be created without any database selected. Select a database by renewing the JWT from the refresh token.

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: