SSKS API ​

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

Headers of the requests ​

Authentication is done through HTTP headers:

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 to true);
• Create a "Session";
• If an identity has previously been stored onto SSKS with this auth_factor (email address or phone number, see the Checking must_authenticate paragraph for details on the comparaison), or if force_auth is set to true, then must_authenticate is set to true; otherwise, to false;
• Return a session_id and must_authenticate;
• If must_authenticate is true, send a challenge to the user, by email or SMS, 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:

Format of the response ​

In JSON format:

Checking task_id status ​

This API endpoint can be used by the server when sending a challenge takes more than 3 seconds.

In that case, /tmr/back/challenge_send/ should have returned a task_id that can be used in this API endpoint.

URL ​

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

Format of the request body ​

This is a POST request in JSON format:

Format of the response ​

In JSON format:

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:

Format of the response ​

In JSON format:

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 ​

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 ​

Response ​

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 ​

Response ​

Retrieve identities ​

This API point can be used to retrieve information regarding stored identities.

URL ​

GET https://{SSKS_URL}/tmr/back/identities/?user_id={user_id}&id={id}&cursor={cursor}

Format of request parameters ​

Response ​

This API point returns the following information in a paginated way.

result follows this schema :

Deleting an identity (2) ​

This API endpoint can be used to remove the identity corresponding to a given id, or all identities stored for a given user_id.

URL ​

DELETE https://{SSKS_URL}/tmr/back/identities/?user_id={user_id}&id={id}

Format of request parameters ​

* One of user_id or id is required, but not both. Using only one of those parameters is enough.

Response ​

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

Normalization of authFactors ​

When using SSKS for 2-man-rule protection, all authFactors sent to SSKS must be normalized. If an authFactor is sent in a non-normalized manner the SSKS server may return an error.

Email normalization ​

Email addresses are normalized by:

• normalizing the string encoding to NFKC
• removing spaces
• making the string lowercase

To do this normalization, you can use the following snippets:

• in Python:

import unicodedata
normalized_email = unicodedata.normalize("NFKC", email).replace(" ", "").lower()

import unicodedata
normalized_email = unicodedata.normalize("NFKC", email).replace(" ", "").lower()

• in JavaScript :

const normalizedEmail = email.normalize('NFKC').replace(/ /g, '').toLowerCase()

const normalizedEmail = email.normalize('NFKC').replace(/ /g, '').toLowerCase()

Normalizing phone numbers ​

For phone numbers, they must be sent in international standard format E.164.

This is simply the phone number, without any spaces, preceded by the country code noted with a +.

For example, the following notations are NOT valid:

• 01 23 45 67 89
• 0123456789
• +33 1 23 45 67 89
• +33-123456789
• 0033123456789

Use the following notation:

+33123456789

To convert any phone number to E.164. format, libraries exist in different languages. For example, to convert a number to E.164 considering that we are in France:

• in Python, you can use phonenumbers :

import phonenumbers
phonenumbers.format_number(phonenumbers.parse("01 23 45 67 89", "FR"), phonenumbers.PhoneNumberFormat.E164)
# '+33123456789'

import phonenumbers
phonenumbers.format_number(phonenumbers.parse("01 23 45 67 89", "FR"), phonenumbers.PhoneNumberFormat.E164)
# '+33123456789'

• in JavaScript, you can use google-libphonenumber :

import libPhoneNumber from 'google-libphonenumber'
const instance = libPhoneNumber.PhoneNumberUtil.getInstance()
instance.format(instance.parse('01 23 45 67 89', 'FR'), libPhoneNumber.PhoneNumberFormat.E164)
// '+33123456789'

import libPhoneNumber from 'google-libphonenumber'
const instance = libPhoneNumber.PhoneNumberUtil.getInstance()
instance.format(instance.parse('01 23 45 67 89', 'FR'), libPhoneNumber.PhoneNumberFormat.E164)
// '+33123456789'

Storage of authFactors ​

The value of authentication factors is not stored in clear text on SSKS. It is first normalized, then hashed. The hash is stored so that it can be verified that the value given is the same when used later.

Also, a de-aliased version is computed, then hashed and stored, so that the SSKS can decide the value of must_authenticate for later requests.

Finally, the auth_factor is also encrypted for a key that the server does not possess, and this encrypted version is stored, so that Seald is able to, if necessary in the future, migrate the hashing procedures.

Migration ​

As of 01/31/2022, the hash function has been updated from v1 to v2 to improve performance by reducing the number of hash iterations.

As of 01/01/2023, the hash function has been updated from v2 to v3 by introducing prior normalization, as well as a de-aliasing mechanism to ensure that a change in case or encoding of the authFactor is not treated as a different authFactor, and that the use of common email aliases does not circumvent authentication.

Since the value of authFactor for which an encrypted identity has been stored in v1 or v2 is not accessible by our teams, we cannot compute the v3 hash for them. Therefore, a migration mechanism has been implemented:

When a request containing an authFactor (POST /tmr/back/challenge_send/, POST /tmr/back/must_authenticate/, POST /tmr/back/delete_user/, POST /tmr/back/identity_check/), SSKS computes the v3 hash, the v2 hash, and the v1 hash, then:

1. if the authFactor has no match on the v3 hash, but has one on the v1 or v2 hash, the authFactor is migrated to the v3 hash and the old hash is deleted.
2. if the authFactor has a match on the v3 hash and has a match on the v1 or v2 hash, a normalization-related collision has occurred which notifies the Seald teams and responds to the client with a 500 error. In this case, the collision must be handled manually, please contact us at support@seald.io.
3. Otherwise, the authFactor has a match on the v3 hash, and not on the v1 and v2 hash, which is the normal operation.

Perform migration ​

To perform the migration on all users, you must:

• For each user in your application:
  • For each authFactor of that user:
    • Make an authenticated call to POST /tmr/back/must_authenticate/ with parameters { "type": <"EM"|"SMS">, "value": <value> }. Please note: you must send the raw, unnormalized value of the authFactor as given when storing the user's identity for the migration to work.

Once done, all known users in your application have been migrated.

You may have other unused identities in your application that should be deleted. To confirm that your migration is complete, please contact us at support@seald.io.

Once you have confirmed with Seald that all users have been migrated, you can normalize the authFactor registered in your application.

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 ​

Response ​

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 ​

Response ​

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

Retrieve identities ​

This API point can be used to retrieve information regarding stored identities.

URL ​

GET https://{SSKS_URL}/strict/back/identities/?user_id={user_id}&id={id}&cursor={cursor}

Format of request parameters ​

Response ​

This API point returns the following information in a paginated way.

result follows this schema :

Deleting an identity (2) ​

This API endpoint can be used to remove the identity corresponding to a given id, or all identities stored for a given user_id.

URL ​

DELETE https://{SSKS_URL}/strict/back/identities/?user_id={user_id}&id={id}

Format of request parameters ​

* One of user_id or id is required, but not both. Using only one of those parameters is enough.

Response ​

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