Connexion initiale

La première requête doit être un login dans un domaine spécifique afin d’obtenir un token (bearer). Ce token devra ensuite être fournit dans les header des requêtes subséquentes.

Authentification

Les modes d’authentification suivants sont acceptés, par ordre de priorité:

une authentification Authorization: Basic, ou un token Authorization: Bearer <token> obtenu suite à ce login, pour tous les appels suivant l’authentification initiale.
à défaut, les headers Sai-Login et Sai-Password décrits ci-dessous.
à défaut, le cookie sainetToken, déposé lors d’une authentification précédente.

Headers de la requête

Header	Type	Requis	Description
`Sai-Login`	String	Oui, si l’authentification `Basic` n’est pas utilisée.	Nom d’utilisateur.
`Sai-Password`	String	Oui, si l’authentification `Basic` n’est pas utilisée.	Mot de passe.

Paramètres d’URL

Paramètre	Type	Requis	Description
`domainId`	String	Oui	Domaine d’authentification.

La requête ci-dessous permet de s’authentifier avec les paramètres mentionnés:

curl --insecure -v \
     -H "Sai-Login: <user>" -H "Sai-Password: <password>" \
     'https://<host>/api/v1/login?domainId=<domain>'

Attention:

Les identifiants de connexion ne doivent jamais être passés en paramètre d’URL: ils se retrouveraient alors en clair dans les logs d’accès d’un éventuel reverse-proxy, dans l’historique du navigateur ainsi que dans le header Referer d’une requête suivante. C’est pour cette raison qu’ils ne sont acceptés qu’au moyen des headers ci-dessus, ou d’une authentification Basic (curl --user <user>:<password>). Une requête qui tenterait malgré tout de passer les identifiants en paramètre d’URL recevra systématiquement une réponse HTTP 401.

Si l’authentification est passée, le serveur renverra le code HTTP 200 ainsi que le message suivant:

{"message":"logged in domain <domain>"}

En cas d’erreur d’accès (codes 401 ou 403), les éléments suivants doivent être vérifiés:

le nom d’utilisateur et mot de passe sont corrects.
l’utilisateur est actif dans SYS02 (ou dans l’ActiveDirectory).
l’accès à l’API a été activé en SYS22.

Info:

Il n’y a pas de paramètre spécial pour qu’un utilisateur ait accès à l’API. Si l’utilisateur peut se connecter à SAINet (via le client riche), alors il a accès l’API.

Headers

Dans la réponse HTTP retournée, il y a 2 valeurs retournées dans les en-têtes (headers):

Cookie	Description
`Sai-Server-Instance`	Nom de l’instance sur lequel la requête a été faite. Cette valeur doit être précisée dans les appels, notamment dans le cas de multi-instances. S’il n’y a qu’une seule instance, ce header n’est pas nécessaire.
`Sai-Bearer-Token`	Token d’authentification pour les appels. Ce token doit être ensuite passé dans le header `Authorization` sous la forme `Authorization: Bearer <token>`. Ce header est nécessaire pour tous les prochains appels.

Les en-têtes se présentent comme suit dans la requête d’authentification (grâce à l’option -v de cURL):

< sai-bearer-token: ZXlKMGVYQWlPaUpLVjFRaUxDSmxZDVySV9Fa3pmMA==
< sai-server-instance: NA

Il suffit de reprendre les valeurs ci-dessus dans les requêtes suivantes:

curl --insecure \
     -H "Sai-Server-Instance: NA" \
     -H "Authorization: Bearer ZXlKMGVYQWlPaUpLVjFRaUxDSmxZDVySV9Fa3pmMA==" \
     'https://<host>/api/v1/SYS02'

Note:

L’option -v génère du texte parasite à l’intérieur de la réponse JSON, le rendant invalide et empêchant son formatting. Il ne faut donc l’utiliser que lors du login afin de récupérer le token d’authentification.