# API de SSKS

L'URL par défaut de SSKS est ssks.seald.io.

# En-têtes des requêtes

L'authentification se fait par des headers HTTP :

Variable	Type	Description
`X-SEALD-APPID` (requis)	String	Application ID, donné sur le tableau d'administration du Seald SDK
`X-SEALD-APIKEY` (requis)	String	Clé d'API, donnée sur le tableau d'administration du Seald SDK
`Content-type`	String	`application/json`

Pour savoir où trouver ces valeurs, référez-vous au paragraphe en question dans le guide concernant l'intégration du 2-man-rule.

# Requêtes pour la protection par 2-man-rule

# Envoi d'un challenge

Ce point d'API est appelé par le serveur de l'application utilisant le SDK, et permet de :

Créer un "utilisateur" au sens de SSKS (si create_user est à true) ;
Créer une "Session" ;
Si une identité a déjà été stockée sur SSKS avec ce auth_factor (adresse email ou numéro de téléphone), ou si force_auth est mis à true, alors must_authenticate est mis à true ; si non, à false ;
Retourner un session_id et must_authenticate ;
Si must_authenticate est true, envoyer un challenge à l'utilisateur, par email ou SMS, le backend ne doit pas avoir accès à ce challenge. Le challenge est valable 6h.

Le backend doit renvoyer le session_id et must_authenticate au frontend, tel qu'expliqué dans le guide d'intégration du 2-man-rule sur le backend.

TIP

L'envoi de challenge par SMS est limité au quota de SMS autorisé pour votre team. Si le quota est dépassé, votre requête recevra une erreur 406 Not Acceptable: {"detail": "SMSQuotaFailed"}.

N'hésitez pas à nous contacter pour augmenter le quota de SMS de votre équipe.

# URL

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

# Format du corps de la requête

Il s'agit d'une requête POST au format JSON :

Variable	Type	Description
`create_user` (default: false)	Boolean	Si `true`, créé un utilisateur s'il n'existe pas. Sinon rejette avec une erreur 404. Si inutilisé, l'application doit manuellement créer un utilisateur
`user_id` (requis)	String	Identifiant unique de l'utilisateur. Peut être un ID, un UUID, une adresse email. La donnée est stockée en clair sur SSKS.
`auth_factor` (requis)	Object	Facteur authentication de l'utilisateur. Utilisée pour envoyer le `challenge`. Peut être identique pour plusieurs utilisateurs tant que le `user_id` est unique.
`auth_factor.type` (requis)	String	Type de facteur d'authentification. `"EM"` pour une adresse email, `"SMS"` pour un numéro de téléphone.
`auth_factor.value` (requis)	String	Adresse e-mail ou numéro de téléphone de l'utilisateur. La valeur n'est pas stockée en clair sur SSKS, elle est hachée de sorte de pouvoir vérifier que la valeur donnée lors d'une utilisation ultérieure est la même. Si c'est un numéro de téléphone, utilisez le format international, avec code de pays et sans séparateurs (ex. `+12065550100`).
`email` (deprecated)	String	Obsolète, utilisez `auth_factor`. Adresse e-mail de l'utilisateur. Utilisée pour envoyer le `challenge`. Elle n'est pas stockée en clair sur SSKS, elle est hachée de sorte de pouvoir vérifier que l'adresse donnée lors d'une utilisation ultérieure est la même.
`force_auth` (default: false)	Boolean	Permet de forcer l'envoi d'un challenge d'authentification, même si ce `auth_factor` n'a jamais été utilisé précédemment.
`template` (requis)	String	Template au format HTML de l'email contenant le challenge d'authentification envoyé à l'utilisateur. Doit contenir le String `$$CHALLENGE$$` qui sera remplacé par le `challenge` par SSKS.
`subject`	String	Objet de l'email envoyé avec le challenge. Défaut à `"End-to-end encryption challenge"`. Ignoré pour le SMS.
`fake_otp` (default: false)	Boolean	Uniquement en environnement de test / staging. Si `true`, n'enverra pas d'email ou SMS. Le challenge sera toujours `aaaaaaaa`. Si `true` en environnement de production, renverra une erreur 406.

# Format de la réponse

Au format JSON :

Variable	Type	Description
`session_id`	String	ID de la session ainsi créée. Doit être transmis au frontend.
`must_authenticate`	Boolean	Booléen indiquant si la session créée a besoin d'un `challenge`. Si `true`, le serveur envoie un email à l'utilisateur, contenant ce `challenge`, qu'il devra répéter dans le frontend dans les 6h. Si `false`, la session peut directement enregistrer son identité sur SSKS sans `challenge`.

# Vérification du `must_authenticate`

Ce point d'API peut être utilisé par le serveur de l'application utilisant le SDK avant d'envoyer le challenge pour vérifier la valeur que prendrait must_authenticate si le point d'api d'envoi était appelé.

Cela permet de déterminer si une identité a déjà été stockée pour un auth_factor donné.

# URL

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

# Format du corps de la requête

Il s'agit d'une requête POST au format JSON :

Variable	Type	Description
`type` (requis)	String	`"EM"` pour une adresse e-mail, `"SMS""` pour un numéro de téléphone
`value` (requis)	String	Adresse e-mail ou numéro de téléphone de l'utilisateur. Si c'est un numéro de téléphone, utilisez le format international, avec code de pays et sans séparateurs (ex. `+12065550100`).

# Format de la réponse

Au format JSON :

Variable	Type	Description
`must_authenticate`	Boolean	Booléen indiquant si la session créée a besoin d'un `challenge`. Si `true`, le serveur devra envoyer un email à l'utilisateur au prochain `send_challenge`.

# Création manuelle d'un utilisateur

Ce point d'API peut être utilisé si create_user est à False sur le point d'API précédent. Cela va juste créer un "utilisateur" vierge au sens de SSKS.

# URL

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

# Format du corps de la requête

Variable	Type	Description
`user_id` (requis)	String	Identifiant unique de l'utilisateur. Peut être un ID, un UUID, une adresse email. La donnée est stockée en clair sur SSKS.
`auth_factor` (requis)	Object	facteur authentication de l'utilisateur. Utilisée pour envoyer le `challenge`.
`auth_factor.type` (requis)	String	Type de facteur d'authentification. 'EM' pour une adresse email, 'SMS' pour un numéro de téléphone.
`auth_factor.value` (requis)	String	Adresse e-mail ou numéro de téléphone de l'utilisateur. La valeur n'est pas stockée en clair sur SSKS, elle est hachée de sorte de pouvoir vérifier que la valeur donnée lors d'une utilisation ultérieure est la même. Si c'est un numéro de téléphone, utilisez le format international, avec code de pays et sans séparateurs (ex. `+12065550100`).
`email` (deprecated)	String	Obsolète, utilisez `auth_factor`. Adresse e-mail de l'utilisateur. Utilisée pour envoyer le `challenge`. Elle n'est pas stockée en clair sur SSKS, elle est hachée de sorte de pouvoir vérifier que l'adresse donnée lors d'une utilisation ultérieure est la même.

# Réponse

Ce point d'API n'a pas d'information à retourner au serveur. Il répond simplement avec {"status": "ok"}.

# Suppression d'un utilisateur

Ce point d'API peut être utilisé pour supprimer toutes les données stockées sur un utilisateur sur SSKS.

# URL

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

# Format du corps de la requête

Variable	Type	Description
`user_id` (requis)	String	Identifiant unique qui avait été utilisé pour créer l'utilisateur à supprimer.
`auth_factor` (optionnel)	Object	Objet contenant les informations d'authentification d'un utilisateur. Si renseigné, uniquement l'utilisateur possédant ce `auth_factor` sera supprimé. (Cela peut être utile en cas de doublons d'`user_id`)
`auth_factor.type` (requis si `auth_factor` est utilisé)	String	Type de facteur d'authentification. 'EM' pour une adresse email, 'SMS' pour un numéro de téléphone.
`auth_factor.value` (requis si `auth_factor` est utilisé)	String	Adresse e-mail ou numéro de téléphone de l'utilisateur. Si c'est un numéro de téléphone, utilisez le format international, avec code de pays et sans séparateurs (ex. `+12065550100`).

# Réponse

Variable	Type	Description
`status`	String	`ok` si la requête s'est déroulée correctement
`deleted`	Number	Nombre d'identité supprimées

# Vérification de l'existence d'une identité

Ce point d'API peut être utilisé pour vérifier si pour un user_id (éventuellement couplé avec un auth_factor) donné une identité protégée en 2-man-rule existe.

Il répond avec le nombre d'identités correspondant à cet utilisateur, soit 0 quand il n'y en a pas ou si l'utilisateur n'existe pas, soit un nombre strictement positif s'il y en a une ou plus.

Il est aussi possible de vérifier s'il y a une identité stockée pour un user_id sans vérifier le auth_factor auquel il est associé.

# URL

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

# Format du corps de la requête

Variable	Type	Description
`user_id` (requis)	String	Identifiant unique qui a été utilisé pour créer l'utilisateur à vérifier.
`auth_factor` (optionnel)	Object	Facteur authentication de l'utilisateur. Utilisée pour envoyer le `challenge`.
`auth_factor.type` (requis si `auth_factor.value` est donné)	String	Type de facteur d'authentification. 'EM' pour une adresse email, 'SMS' pour un numéro de téléphone.
`auth_factor.value` (requis si `auth_factor.type` est donné)	String	Adresse e-mail ou numéro de téléphone de l'utilisateur. Si c'est un numéro de téléphone, utilisez le format international, avec code de pays et sans séparateurs (ex. `+12065550100`).

# Réponse

Variable	Type	Description
`identities_count`	Number	Nombre d'identités stockées pour ce `user_id` éventuellement filtré par `auth_factor`.
`user`	Object	Informations sur l'utilisateur requêté
`user.user_id`	Object	`user_id` donné dans la requête
`user.app_id`	Object	`app_id` de l'application dans Seald

# Requêtes pour la protection par mot de passe

# Vérification de l'existence d'une identité

Ce point d'API peut être utilisé pour vérifier si un user_id donné a une ou plusieurs identités qui sont stockées protégées par mot de passe.

Il répond avec le nombre d'identités correspondant à cet utilisateur, soit 0 quand il n'y en a pas, soit un nombre strictement positif s'il y en a.

# URL

POST https://{SSKS_URL}/strict/back/identity_check/

# Format du corps de la requête

Variable	Type	Description
`user_id` (requis)	String	Identifiant unique qui a été utilisé pour créer l'utilisateur à vérifier.

# Réponse

Variable	Type	Description
`identities_count`	Number	Nombre d'identités stockées pour ce `user_id`.
`user`	Object	Informations sur l'utilisateur requêté
`user.user_id`	Object	`user_id` donné dans la requête
`user.app_id`	Object	`app_id` de l'application dans Seald

# Suppression d'identité

Ce point d'API peut être utilisé pour supprimer toutes les identités stockées pour le compte d'un user_id.

Il n'est pas possible de distinguer plusieurs identités d'un même utilisateur. On ne peut donc que les supprimer conjointement.

# URL

POST https://{SSKS_URL}/strict/back/identity_delete/

# Format du corps de la requête

Variable	Type	Description
`user_id` (requis)	String	Identifiant unique qui avait été utilisé pour créer l'utilisateur à supprimer.

# Réponse

Ce point d'API n'a pas d'information à retourner au serveur. Il répond simplement avec {"status": "ok"}.

← Interface: AnonymousSDK DashboardAPI Authentification →

# API de SSKS

# En-têtes des requêtes

# Requêtes pour la protection par 2-man-rule

# Envoi d'un challenge

# URL

# Format du corps de la requête

# Format de la réponse

# Vérification du must_authenticate

# URL

# Format du corps de la requête

# Format de la réponse

# Création manuelle d'un utilisateur

# URL

# Format du corps de la requête

# Réponse

# Suppression d'un utilisateur

# URL

# Format du corps de la requête

# Réponse

# Vérification de l'existence d'une identité

# URL

# Format du corps de la requête

# Réponse

# Requêtes pour la protection par mot de passe

# Vérification de l'existence d'une identité

# URL

# Format du corps de la requête

# Réponse

# Suppression d'identité

# URL

# Format du corps de la requête

# Réponse

# Vérification du `must_authenticate`