# SSKS API

The default URL of SSKS is ssks.seald.io.

# Headers of the requests

Authentication is done through HTTP headers:

Variable Type Description
X-SEALD-APPID (required) String Application ID, given on the Seald SDK administration dashboard
X-SEALD-APIKEY (required) String API key, given on the Seald SDK administration dashboard
Content-type String application/json

To learn where you can get these, you can check the paragraph about it in the 2-man-rule integration guide.

# Requests

# Sending a challenge

This API endpoint is called by the application server using the SDK, and allows to:

  • Create a "user" in the sense of SSKS (if create_user is set to True);
  • Create a "Session";
  • If an identity has previously been stored onto SSKS with this email address, must_authenticate is set to true; otherwise, to false;
  • Return a session_id and must_authenticate;
  • If must_authenticate is true, send a challenge by email to the user, the backend must not have access to this challenge. The challenge is valid for 6h.

The backend must return the session_id and must_authenticate to the frontend, as explained in the 2-man-rule integration guide.

# URL

POST https://{SSKS_URL}/tmr/back/challenge_send/

# Format of the request body

This is a POST request in JSON format:

Variable Type Description
create_user (default: false) Boolean If true, creates a user if it does not exist. Otherwise rejects with a 404 error. If unused, the application must manually create a user
user_id (required) String Unique identifier of the user. Can be an ID, a UUID, an email address or any string identifier unique to this user in the context of your application. The data is stored in clear text on SSKS.
email (required) String User's email address. Used to send the challenge. It is not stored in clear text on SSKS, it is hashed so that it can be verified that the address given is the same when used later.
template (required) String Template in HTML format of the email sent to the user containing the authentication challenge. Must contain the String $$CHALLENGE$$ which will be replaced by the challenge by SSKS.

# Format of the response

In JSON format:

Variable Type Description
session_id String ID of the newly created session. Must be transmitted to the frontend.
must_authenticate Boolean Boolean indicating if the newly created session needs a challenge. If true, the server sends an email to the user, containing this challenge, which they will need to repeat in the frontend in the next 6h. If false, the session can directly save the identity on SSKS without a challenge.

# Manual creation of a user

This API point can be used if create_user is set to False on the previous API point. This will just create a blank "user" in the sense of SSKS.

# URL

POST https://{SSKS_URL}/tmr/back/create_user/

# Format of the request body

Variable Type Description
user_id (required) String Unique identifier of the user. Can be an ID, a UUID, an email address or any string identifier unique to this user in the context of your application. The data is stored in clear text on SSKS.
email (required) String User's email address. Used to send the challenge. It is not stored in clear text on SSKS, it is hashed so that it can be verified that the address given is the same when used later.

# Response

This API point does not have any information to return to the server. It simply responds with {"status": "ok"}.

# Deletion of a user

This API point can be used to delete all data stored on a user on SSKS.

# URL

POST https://{SSKS_URL}/tmr/back/delete_user/

# Format of the request body

Variable Type Description
user_id (required) String Unique identifier that was used to create the user to delete.

# Response

This API point does not have any information to return to the server. It simply responds with {"status": "ok"}.