Authentification API

Pour effectuer des requêtes à l'API, vous aurez besoin :

• d'une clé API (apikey), identifiant l'application
• ET d'un email + mot de passe, identifiant l'utilisateur

L'utilisateur peut être identifié via :

• HTTP Basic : le login/mdp est envoyé dans chaque requête.
• Une session : première requête de connexion, puis envoie du header de session dans les requêtes suivantes.

---

Clé d’utilisation API

L’utilisation de l’API est restreinte par une clé d’utilisation, identifiant une application.

La clé doit être envoyée à chaque requête sur l’API, en utilisant le paramètre apikey.

Important Le paramètre apikey doit toujours être passé dans les paramètres d'URL, et jamais dans le body de la requête.

Par exemple, pour une requête GET :

GET /api/v1/groups?apikey=xxxxxx

Pour une requête POST avec un Content-Type: application/json :

POST /api/v1/groups/4/calendars?apikey=xxxxxx
{
   "calendar" : {
     …
   }
}

Note Les clés API sont différentes entre l’environnement « sandbox » et l’environnement de production.

---

HTTP Basic

L’API ClicRDV permet une authentification HTTP Basic.

Note Le mot de passe est encrypté dans la communication SSL du protocole HTTPS.

Exemple avec Curl, en utilisant l'option -u pour spécifier l'utilisateur HTTP Basic :

$ curl -u "[email protected]:secret"
       "https://www.clicrdv.com/api/v1/groups.json?apikey=xxxxxx"

Important L'API ClicRDV n'envoie pas de réponse 401 lors d'une tentative d'accès à une ressource protégée. Il appartient donc au client de toujours envoyer le header Authorization: Basic base64(email+':'+password)

---

Sessions

Vous pouvez ouvrir une session grâce à la requête suivante :

POST /api/v1/sessions/login

Les paramètres à envoyer dépendent du type d’utilisateur avec lequel vous vous connectez :

• Pour utiliser l’API de prise de RDV : account[email] et account[password]
• Pour utiliser l’API de l'agenda : pro[email] et pro[password]

Dans les deux cas, le mot de passe doit être encodé en SHA1. (Vous pouvez utiliser ce site pour rapidement convertir un mot de passe en SHA1)

Voici un exemple avec Curl :

$ curl -i -X POST  "https://sandbox.clicrdv.com/api/v1/sessions/login.json?apikey=xxxxxx&\
                    pro%5Bemail%5D=fake.user%40gmail.com&\
                    pro%5Bpassword%5D=a94a8fe5ccb19ba61c4c0873d391e987982fbbd3\"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200
Content-Length: 283
Set-Cookie: _session_id=4e8c5362ed2abeddca00000c; path=/; HttpOnly

{"pro":{"created_at":"2007-03-30 15:09:07","updated_at":"2011-10-05 14:52:07",\
"synched_at":"2011-09-29 19:50:18","lastname":"Fake","id":9,"firstname":"User",\
"cellphone":"06 12 34 56 78","email":"[email protected]},"error":null\}

Note Les %5B et %5D correspondent aux caractères '[' et ']' encodés.

L’identifiant de Session est renvoyé dans l’entête de réponse HTTP Set-Cookie. Ici :

Set-Cookie: _session_id=4e8c5362ed2abeddca00000c; path=/; HttpOnly

Pour les requêtes suivantes, il faut ensuite renvoyer dans le header Cookie le paramètre _session_id :

Cookie: _session_id=4e8c5362ed2abeddca00000c

Exemple avec Curl, l'option -H permettant d'ajouter un header HTTP :

$ curl -i -H 'Cookie: _session_id=4e8c5362ed2abeddca00000c'
       "https://sandbox.clicrdv.com/api/v1/groups.json"

Note Les sessions expirent au bout d'une heure d’inactivité.

---