Authentication

Every call to the Web API must be authenticated via an authentication token and a session token. Such tokens can be fetched using the POST /account/login/ and POST /account/session Web API endpoints.

These tokens can then be reused as many times as possible to authenticate any following request to the Web API.

Getting Tokens¶

Getting an authentication Token¶

First, obtain the authentication token using a POST request to the /account/login/ endpoint with your username and password. The response includes an authentication token in the cookies field.

curl --location --request POST 'https://smartshape.io/account/login/' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "username":"test",
        "password":"test"
    }'

Here is the expected answer:

{
    "success": true,
    "email": "test@smartshape.io.test",
    "username": "test",
    "cookies": "jsonwebtoken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3RAc21hcnRzaGFwZS5pby50ZXN0IiwiaWF0IjoxNTkyODUwNDY4fQ.WABvpFFLzgp7gt0Czi8-WGAs8A7wzu6pFk7SSsNq4TNi0lBJLj-nJ6Q48Ocabfd6MkwYto-TSlVi0Gpos8o1JqwwySBRxClxaVZ8RNxE-DfLcG7cglDlBfUElUEbma324ADABrMZnP9NTahuNwNflDGiccpwaHOtazrmWxX2lJY4GvU9ERTF9GHhATZ7AVuh5e6u48z5KKam1S_IJ6Ojkx3Gum6JBovQO2XsQKG-_Dz5PjG7jXzSyByHtOxiySmc-Xk1Cq2Y7cWq_nE0qiYnrJ-fVsbv6QLFYygA-A3I5Sb9LFIupHlNuTqWUYjuUMh8fWK5hRuj1eEcL2upOlHXZGtist5I6onvtjxgaY64oPQG0_NSbuYKxX1M9zgVQQiVu2CGlsKLNVnOO7Cb-3jfuxaDF5QH2lb2uEjsmUDQTNbUhmE1D9IuYBfMknI0umOG5gOx8DyimEHhEoHJaKGUeyI-Xai5lOLIYpQfIHwycoWcpiktQO8Rln9OvYhv2tVDi9QJmRxLlQxDyBg0cc4bL___ZXm-1jWf4c2FcHLXxyi1yTgftVUKd7sZl2azI9Gc_J3suENzstgyohLRfcAHSfdCt2sXhJEt-_Jufn95k04p_MKqD4q2okhVSuttt24gTVsTZNqPQ8svGXVxovWfGodUjQU_1Td5DjhWkhCfNJY"
}

The authentication token is the part after the = in the cookies field. In the example above, the authentication token is:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3RAc21hcnRzaGFwZS5pby50ZXN0IiwiaWF0IjoxNTkyODUwNDY4fQ.WABvpFFLzgp7gt0Czi8-WGAs8A7wzu6pFk7SSsNq4TNi0lBJLj-nJ6Q48Ocabfd6MkwYto-TSlVi0Gpos8o1JqwwySBRxClxaVZ8RNxE-DfLcG7cglDlBfUElUEbma324ADABrMZnP9NTahuNwNflDGiccpwaHOtazrmWxX2lJY4GvU9ERTF9GHhATZ7AVuh5e6u48z5KKam1S_IJ6Ojkx3Gum6JBovQO2XsQKG-_Dz5PjG7jXzSyByHtOxiySmc-Xk1Cq2Y7cWq_nE0qiYnrJ-fVsbv6QLFYygA-A3I5Sb9LFIupHlNuTqWUYjuUMh8fWK5hRuj1eEcL2upOlHXZGtist5I6onvtjxgaY64oPQG0_NSbuYKxX1M9zgVQQiVu2CGlsKLNVnOO7Cb-3jfuxaDF5QH2lb2uEjsmUDQTNbUhmE1D9IuYBfMknI0umOG5gOx8DyimEHhEoHJaKGUeyI-Xai5lOLIYpQfIHwycoWcpiktQO8Rln9OvYhv2tVDi9QJmRxLlQxDyBg0cc4bL___ZXm-1jWf4c2FcHLXxyi1yTgftVUKd7sZl2azI9Gc_J3suENzstgyohLRfcAHSfdCt2sXhJEt-_Jufn95k04p_MKqD4q2okhVSuttt24gTVsTZNqPQ8svGXVxovWfGodUjQU_1Td5DjhWkhCfNJY

Getting a SmartShape session Token¶

Next, use the authentication token to request a session token. Send a POST request to /account/session with the authentication token in the Authorization header. The response will provide a session token in the jwt field.

You need to have a valid authentication token ($AUTHENTICATION_TOKEN) in order to get a session token.

curl -X POST -ks https://smartshape.io/account/session \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $AUTHENTICATION_TOKEN"

Here the expected answer:

{
  "success": true,
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uVXVpZCI6ImZkNjdlYzBjLTIwYTgtNGYyYS04N2ZiLTRlOWEwN2RiYTlkMiIsImlhdCI6MTcwMDA2MDE2OX0.f-fhfVVEorLv-Nzc7QSMkcyFMcsK-RX4p-VQ2GR_y36UP5Qe6vY2hDw13CLRa7kr3NWM9rjKCTjOloKd6KCZ_TD_rUhhiRejN-kViOgZML3FKDlmBPXFv7ptxjpUXM9TPSMsy8wClbOjoJqk9lc_47fQQpHPMF71mWu4fm6DQLNcRIpFDb9H7RE7ag1nXpsGXvhDHOfKvkS0mQLFpnS02czRhokb58ZSUe0XQ_pDXUbFuwM2R3tnc2oh4n-GUj0iORBfAvlLnUU-UqcyZQmt3o6lAQ0_OEme2LHLOdcoZhvKSkFQ_DhUmIxDKiVZzTFyPqyo77mQ1XR9G56ltao4pv1WSZjTfimKYmLFRbod4YmKB5me8AL4ZBKC88PDlF2vb1JfXHtQHpwsscWsRwhj1S29jQ1uwOnGVfQR7LS4UteVbcc7fa-GPniQH8jrcrxGMQva383jtx_btnkoWw_U0ty-pQhrIa6MO3-S60AYRMivPZmlhlX7oLQJbnlJZAq86YBFVscryKCIvl-OBqpuI2qEGyfNOG6k72Suv6N35t7lGQOysxPixIXQsmzLXEaZWv0vK-rjDowG9YE_T1dpB27SFJMo0NwMDzevs5GMEzaHQx6oj4OXp3Ggiu7nYh4Z01CQJ5YODuDxROUldwQslnnZScHuKmGcIVqI3sdbaNI"
}

The session token is in the jwt field and set as the X-SmartShape-Session cookie.

Authenticating requests to the Web API¶

There are two ways to authenticate a request to the Web API:

Using the Authorization and X-SmartShape-Session HTTP headers.
Using cookies (i.e. the Cookies HTTP header).

You can choose one or the other. But you must not use both at the same time.

The `Authorization` and `X-SmartShape-Session` HTTP headers¶

The authorization token is expected to be passed to every Web API call using the Authorization and X-SmartShape-Session HTTP headers. The expected values for these HTTP headers are respectively:

Bearer <the-auth-token>

and

<the-session-token>

For example, the following call to curl makes an authenticated call to the GET /file/dir/private/ Web API endpoint in order to list all the files in the root directory of the test user (identified by the authentication token we fetched in our previous example):

curl -X GET 'http://smartshape.io/file/dir/private/' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3RAc21hcnRzaGFwZS5pby50ZXN0IiwiaWF0IjoxNTkyODUwNDY4fQ.WABvpFFLzgp7gt0Czi8-WGAs8A7wzu6pFk7SSsNq4TNi0lBJLj-nJ6Q48Ocabfd6MkwYto-TSlVi0Gpos8o1JqwwySBRxClxaVZ8RNxE-DfLcG7cglDlBfUElUEbma324ADABrMZnP9NTahuNwNflDGiccpwaHOtazrmWxX2lJY4GvU9ERTF9GHhATZ7AVuh5e6u48z5KKam1S_IJ6Ojkx3Gum6JBovQO2XsQKG-_Dz5PjG7jXzSyByHtOxiySmc-Xk1Cq2Y7cWq_nE0qiYnrJ-fVsbv6QLFYygA-A3I5Sb9LFIupHlNuTqWUYjuUMh8fWK5hRuj1eEcL2upOlHXZGtist5I6onvtjxgaY64oPQG0_NSbuYKxX1M9zgVQQiVu2CGlsKLNVnOO7Cb-3jfuxaDF5QH2lb2uEjsmUDQTNbUhmE1D9IuYBfMknI0umOG5gOx8DyimEHhEoHJaKGUeyI-Xai5lOLIYpQfIHwycoWcpiktQO8Rln9OvYhv2tVDi9QJmRxLlQxDyBg0cc4bL___ZXm-1jWf4c2FcHLXxyi1yTgftVUKd7sZl2azI9Gc_J3suENzstgyohLRfcAHSfdCt2sXhJEt-_Jufn95k04p_MKqD4q2okhVSuttt24gTVsTZNqPQ8svGXVxovWfGodUjQU_1Td5DjhWkhCfNJY' \
    --header 'X-SmartShape-Session: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uVXVpZCI6ImZkNjdlYzBjLTIwYTgtNGYyYS04N2ZiLTRlOWEwN2RiYTlkMiIsImlhdCI6MTcwMDA2MDE2OX0.f-fhfVVEorLv-Nzc7QSMkcyFMcsK-RX4p-VQ2GR_y36UP5Qe6vY2hDw13CLRa7kr3NWM9rjKCTjOloKd6KCZ_TD_rUhhiRejN-kViOgZML3FKDlmBPXFv7ptxjpUXM9TPSMsy8wClbOjoJqk9lc_47fQQpHPMF71mWu4fm6DQLNcRIpFDb9H7RE7ag1nXpsGXvhDHOfKvkS0mQLFpnS02czRhokb58ZSUe0XQ_pDXUbFuwM2R3tnc2oh4n-GUj0iORBfAvlLnUU-UqcyZQmt3o6lAQ0_OEme2LHLOdcoZhvKSkFQ_DhUmIxDKiVZzTFyPqyo77mQ1XR9G56ltao4pv1WSZjTfimKYmLFRbod4YmKB5me8AL4ZBKC88PDlF2vb1JfXHtQHpwsscWsRwhj1S29jQ1uwOnGVfQR7LS4UteVbcc7fa-GPniQH8jrcrxGMQva383jtx_btnkoWw_U0ty-pQhrIa6MO3-S60AYRMivPZmlhlX7oLQJbnlJZAq86YBFVscryKCIvl-OBqpuI2qEGyfNOG6k72Suv6N35t7lGQOysxPixIXQsmzLXEaZWv0vK-rjDowG9YE_T1dpB27SFJMo0NwMDzevs5GMEzaHQx6oj4OXp3Ggiu7nYh4Z01CQJ5YODuDxROUldwQslnnZScHuKmGcIVqI3sdbaNI'

The `jsonwebtoken` and `X-SmartShape-Session` cookies¶

If your client app provides a "cookie jar", it might be easier to set the tokens once as a cookie. The cookie jar should then set the Cookie HTTP header automatically for you.

The two tokens can be set in cookies named jsonwebtoken for the authentication token and X-SmartShape-Session for the session token.

For example, the following call to curl makes an authenticated call to the GET /file/dir/private/ Web API endpoint in order to list all the files in the root directory of the test user (identified by the authentication token we fetched in our previous example):

curl -X GET 'http://smartshape.io/file/dir/private/' \
    --header 'Cookie: jsonwebtoken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3RAc21hcnRzaGFwZS5pby50ZXN0IiwiaWF0IjoxNTkyODUwNDY4fQ.WABvpFFLzgp7gt0Czi8-WGAs8A7wzu6pFk7SSsNq4TNi0lBJLj-nJ6Q48Ocabfd6MkwYto-TSlVi0Gpos8o1JqwwySBRxClxaVZ8RNxE-DfLcG7cglDlBfUElUEbma324ADABrMZnP9NTahuNwNflDGiccpwaHOtazrmWxX2lJY4GvU9ERTF9GHhATZ7AVuh5e6u48z5KKam1S_IJ6Ojkx3Gum6JBovQO2XsQKG-_Dz5PjG7jXzSyByHtOxiySmc-Xk1Cq2Y7cWq_nE0qiYnrJ-fVsbv6QLFYygA-A3I5Sb9LFIupHlNuTqWUYjuUMh8fWK5hRuj1eEcL2upOlHXZGtist5I6onvtjxgaY64oPQG0_NSbuYKxX1M9zgVQQiVu2CGlsKLNVnOO7Cb-3jfuxaDF5QH2lb2uEjsmUDQTNbUhmE1D9IuYBfMknI0umOG5gOx8DyimEHhEoHJaKGUeyI-Xai5lOLIYpQfIHwycoWcpiktQO8Rln9OvYhv2tVDi9QJmRxLlQxDyBg0cc4bL___ZXm-1jWf4c2FcHLXxyi1yTgftVUKd7sZl2azI9Gc_J3suENzstgyohLRfcAHSfdCt2sXhJEt-_Jufn95k04p_MKqD4q2okhVSuttt24gTVsTZNqPQ8svGXVxovWfGodUjQU_1Td5DjhWkhCfNJY; X-SmartShape-Session= eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uVXVpZCI6ImZkNjdlYzBjLTIwYTgtNGYyYS04N2ZiLTRlOWEwN2RiYTlkMiIsImlhdCI6MTcwMDA2MDE2OX0.f-fhfVVEorLv-Nzc7QSMkcyFMcsK-RX4p-VQ2GR_y36UP5Qe6vY2hDw13CLRa7kr3NWM9rjKCTjOloKd6KCZ_TD_rUhhiRejN-kViOgZML3FKDlmBPXFv7ptxjpUXM9TPSMsy8wClbOjoJqk9lc_47fQQpHPMF71mWu4fm6DQLNcRIpFDb9H7RE7ag1nXpsGXvhDHOfKvkS0mQLFpnS02czRhokb58ZSUe0XQ_pDXUbFuwM2R3tnc2oh4n-GUj0iORBfAvlLnUU-UqcyZQmt3o6lAQ0_OEme2LHLOdcoZhvKSkFQ_DhUmIxDKiVZzTFyPqyo77mQ1XR9G56ltao4pv1WSZjTfimKYmLFRbod4YmKB5me8AL4ZBKC88PDlF2vb1JfXHtQHpwsscWsRwhj1S29jQ1uwOnGVfQR7LS4UteVbcc7fa-GPniQH8jrcrxGMQva383jtx_btnkoWw_U0ty-pQhrIa6MO3-S60AYRMivPZmlhlX7oLQJbnlJZAq86YBFVscryKCIvl-OBqpuI2qEGyfNOG6k72Suv6N35t7lGQOysxPixIXQsmzLXEaZWv0vK-rjDowG9YE_T1dpB27SFJMo0NwMDzevs5GMEzaHQx6oj4OXp3Ggiu7nYh4Z01CQJ5YODuDxROUldwQslnnZScHuKmGcIVqI3sdbaNI'

Important notes about sessions¶

Each session locks a license token. Trying to create a session when there's no license token available results in an error.

Trying to create a session when there's already a session created for the current user results in:

A new session token returned by the endpoint.
The old session token being invalidated, it can no longer be used to call the API.
The license token of the old session being transfered to the new session.

Once authenticated, the session token must be kept alive by calling PUT /account/session at least every hour, otherwise the session will expire in one hour.

Calling DELETE /account/session to delete a session doesn't delete it immediately but 5 minutes later.

Single Sign On¶

Trusted third party applications can create and sign valid authentication tokens using the same private key that the SmartShape server uses. Using this method, trusted third party apps do not even need the user's password to create a valid authentication token. But only the private key.

Attention: that private key must be considered highly sensitive. Gaining access to the private key will allow anyone to create valid authentication tokens for any user, effectively impersonating any user and steal all the data hosted on the corresponding SmartShape instance. That private key must be stored securely.

The following code samples uses the jsonwebtoken package to create a valid SmartShape authentication token for the user identified by the Account ID:

const jsonwebtoken = require('jsonwebtoken');

function createSignedJWT(accountId, key) {
    return jsonwebtoken.sign({id: accountId}, key, {algorithm: 'RS256'});
}

In the code above, key is actually a String or Buffer filled with the content of the private key.

January 16, 2024 March 27, 2019