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.

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. Le domaine `ALL` est interdit dans l’API REST.

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

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.

Descripteur OpenAPI

Le point d’entrée de connexion dispose de son propre descripteur OpenAPI, accessible selon la même convention <resource>/$openapi?domainId=<domain> que celle utilisée pour les tâches:

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

Token d’accès personnel

Pour une intégration automatisée (logiciel tiers, script), un token d’accès personnel peut remplacer le login. Il est créé dans SAINet (tâche SYS02, menu contextuel Tokens API) et son secret n’est affiché qu’une seule fois. Il a le format saipat_<...>.

Un token d’accès personnel :

se passe uniquement dans le header Authorization: Bearer saipat_<...>, à chaque appel ;
ne nécessite pas de login préalable : aucun header Sai-Bearer-Token ni cookie n’est retourné et aucune session n’est créée ;
exige le paramètre d’URL domainId sur chaque appel (société dans laquelle la requête est exécutée, qui doit faire partie des sociétés du token ; le domaine ALL est interdit) ;
ne donne accès qu’aux tâches (en lecture et en écriture) définies sur le token, dans la limite des droits de son propriétaire ; si aucune tâche n’est définie (ni en lecture, ni en écriture), il n’ajoute aucune restriction de tâche et les droits du propriétaire s’appliquent ;
a une date de fin (obligatoire à la saisie, sauf pour un compte système ; sans date de fin, le token n’expire pas) et peut être invalidé à tout moment.

curl --insecure \
     -H "Authorization: Bearer saipat_<token>" \
     'https://<host>/api/v1/<TASK>?domainId=<domain>'

Les restrictions suivantes s’appliquent :

le point d’entrée login (et son descripteur login/$openapi) est refusé avec le code HTTP 403 ;
le header Sai-Bearer-Token n’est pas accepté ;
un token passé dans un cookie ou en paramètre d’URL (?token=) est refusé avec le code HTTP 401 ;
un token expiré, invalidé ou inconnu est refusé avec le code HTTP 401 ;
les tâches de rechargement du paramétrage (SYS46) et du code (SYS87) ne sont jamais accessibles avec un token.

Un token peut faire tout ce que son propriétaire peut faire via l’interface : il est donc recommandé de restreindre son périmètre (tâches, sociétés) au strict nécessaire, en particulier pour un compte super administrateur.

Ce mode d’authentification est disponible dès que l’API est activée en SYS22 (variable system.api_enabled à true) (voir l’activation de l’API).