# 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 for 2-man rule protection
# 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 totrue
); - Create a "Session";
- If an identity has previously been stored onto SSKS with this
auth_factor
(email address or phone number), or ifforce_auth
is set totrue
, thenmust_authenticate
is set totrue
; otherwise, tofalse
; - Return a
session_id
andmust_authenticate
; - If
must_authenticate
istrue
, send achallenge
to the user, by email or SMS, the backend must not have access to thischallenge
. Thechallenge
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.
TIP
Sending challenges by SMS is limited to the SMS quota authorized for your team.
If the quota is exceeded, your request will receive an error
406 Not Acceptable: {"detail": "SMSQuotaFailed"}
.
Do not hesitate to contact us to increase the SMS quota for your team.
# 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. |
auth_factor (required) | Object | Authentication method of this user. Used to send the challenge . Can be the same for multiple users as long as the user_id is unique. |
auth_factor.type (required) | String | Type of authentication factor. "EM" for email address, "SMS" for phone number. |
auth_factor.value (required) | String | User's email address or phone number. It is not stored in clear text on SSKS, it is hashed so that it can be verified that the value given is the same when used later. If it is a phone number, use the international format, with the country code and no separators (e.g. +12065550100 ). |
email (deprecated) | String | Deprecated, use auth_factor . 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. |
force_auth (default: false) | Boolean | This forces the sending of an authentication challenge, even if this auth_factor has never been used before. |
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. |
subject | String | Subject line of the email containing the challenge. Defaults to "End-to-end encryption challenge" . Ignored in case of SMS. |
fake_otp (default: false) | Boolean | Only in test / staging environment. If true , email or SMS won't be sent. The challenge will always be aaaaaaaa . If true in production environment, a 406 error will be thrown. |
# 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 . |
# Checking must_authenticate
This API endpoint can be used by the server of the app that uses the SDK before sending a challenge to check what value must_authenticate
would take if the send challenge endpoint were called.
It allows checking if an identity has already been stored for a given auth_factor
.
# URL
POST https://{SSKS_URL}/tmr/back/must_authenticate/
# Format of the request body
This is a POST
request in JSON
format:
Variable | Type | Description |
---|---|---|
type (required) | String | Type of authentication factor. "EM" for email address, "SMS" for phone number. |
value (required) | String | User's email address or phone number. If it is a phone number, use the international format, with the country code and no separators (e.g. +12065550100 ). |
# Format of the response
In JSON
format:
Variable | Type | Description |
---|---|---|
must_authenticate | Boolean | Boolean indicating if the newly created session needs a challenge . If true , the server would send an email or SMS to the user if the send_challenge endpoint were to be used. |
# 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. |
auth_factor (required) | Object | Authentication method of this user. Used to send the challenge . |
auth_factor.type (required) | String | Type of authentication factor. 'EM' for email address, 'SMS' for phone number. |
auth_factor.value (required) | String | User's email address or phone number. It is not stored in clear text on SSKS, it is hashed so that it can be verified that the value given is the same when used later. If it is a phone number, use the international format, with the country code and no separators (e.g. +12065550100 ). |
email (deprecated) | String | Deprecated, use auth_factor . 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. |
auth_factor (optional) | Object | Object containing information regarding user authentication. If used, only the user with corresponding auth_factor will be deleted. (It can be useful is there are multiple users with the same user_id ) |
auth_factor.type (required if auth_factor is used) | String | Type of authentication factor. 'EM' for email address, 'SMS' for phone number. |
auth_factor.value (required if auth_factor is used) | String | User's email address or phone number. If it is a phone number, use the international format, with the country code and no separators (e.g. +12065550100 ). |
# Response
Variable | Type | Description |
---|---|---|
status | String | ok if the request performed correctly |
deleted | Number | Number of identities deleted |
# Checking an identity exists
This API point can be used to check if a given user_id
(possibly with a specific auth_factor
) has a 2-man-rule protected identity.
It responds with the number of identities corresponding to that user, either 0
when there is none or the user does not exists, or a stricly positive integer if there is one or more.
It is also possible to check if there is an identity stored for a user_id
without checking the auth_factor
it is associated with.
# URL
POST https://{SSKS_URL}/tmr/back/identity_check/
# Format of the request body
Variable | Type | Description |
---|---|---|
user_id (required) | String | Unique identifier that was used to create the user to check. |
auth_factor (optional) | Object | Authentication method of this user. Used to send the challenge . |
auth_factor.type (required if auth_factor.value is given) | String | Type of authentication factor. 'EM' for email address, 'SMS' for phone number. |
auth_factor.value (required if auth_factor.type is given) | String | User's email address or phone number. If it is a phone number, use the international format, with the country code and no separators (e.g. +12065550100 ). |
# Response
Variable | Type | Description |
---|---|---|
identities_count | Number | Number of identities stored for this user_id , maybe filtered with the auth_factor . |
user | Object | Data about the requested user |
user.user_id | Object | user_id given in the request |
user.app_id | Object | app_id of the application for Seald |
# Requests for password protection
# Checking an identity exists
This API endpoint can be used to check if a given user_id
has one or more identities stored protected with a passsword.
It responds with identities_count
which represents how many identities there are for this user. It can either be 0
if there are none, or a strictly positive integer.
# URL
POST https://{SSKS_URL}/strict/back/identity_check/
# Format of the request body
Variable | Type | Description |
---|---|---|
user_id (required) | String | Unique identifier that was used to create the user to check. |
# Response
Variable | Type | Description |
---|---|---|
identities_count | Number | Number of identities stored for this user_id . |
user | Object | Data about the requested user |
user.user_id | Object | user_id given in the request |
user.app_id | Object | app_id of the application for Seald |
# Deleting an identity
This API endpoint can be used to remove all identities stored for a given user_id
.
It is not possible to distinguish different identities of a user. Therefore, it is only possible to remove them jointly.
# URL
POST https://{SSKS_URL}/strict/back/identity_delete/
# Format of the request body
Variable | Type | Description |
---|---|---|
user_id (requis) | 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"}
.