Ce guide vous expliquera en quelques étapes comment faire votre premier appel à l'API.

Création des identificants

.

Création des clés de votre application

L'authentification se compose de deux clés. La premier est celle de l'application. Toute application voulant communiquer avec l'API d'OVH doit être préalablement déclarée.
Cliquez sur le lien suivant : https://ca.api.ovh.com/createApp/, indiquez votre identifiant client, votre mot de passe ainsi que le nom que vous donnez à votre application. Le nom sera utile plus tard si vous souhaitez permettre à d'autres personnes de l'utiliser.
Vous obtiendrez deux clés :
  • la clé de l'application, appelée AK, par exemple :
  • 7kbG7Bk7S9Nt7ZSV

  • la clé secrète de votre application, appelée AS, par exemple :
  • EXEgWIz07P0HYwtQDs7cNIqCiQaWSuHF
.

Demander un Token d'authentification à OVH

Maintenant que vous possédez vos clés, vous pouvez demander à OVH un token permettant de faire les requêtes à l'API. Pour ce faire, vous devez faire un appel à https://ca.api.ovh.com/1.0/auth/credential en spécifiant quel(s) accès vous demandez.
Dans notre exemple, nous allons demander à OVH un token en lecture seule à toute l'API.
Exemple avec cURL :
$ curl -XPOST -H"X-Ovh-Application: 7kbG7Bk7S9Nt7ZSV" -H "Content-type: application/json" \
https://ca.api.ovh.com/1.0/auth/credential  -d '{
    "accessRules": [
        {
            "method": "GET",
            "path": "/*"
        }
    ],
    "redirection":"https://www.mywebsite.com/"
}'
{"validationUrl":"https://ca.api.ovh.com/auth/?credentialToken=iQ1joJE0OmSPlUAoSw1IvAPWDeaD87ZM64HEDvYq77IKIxr4bIu6fU8OtrPQEeRh","consumerKey":"MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1","state":"pendingValidation"}
.

Relier le token d'authentification avec un compte client OVH

Dans la réponse vous voyez qu'on vous envoie une URL de validation ainsi qu'une consumerKey (le token, appelé CK). Pour le moment ce token n'est lié à aucun identifiant client. C'est en s'identifiant via l'URL que vous (ou un autre client) lierez votre compte OVH avec ce token.

Cette étape vous permettra d'identifier n'importe quel client OVH et d'obtenir des droits sur son compte. Cela peut être utile si vous souhaitez développer une application pour la communauté. Sinon, identifiez-vous directement sur la page.

Ce token a pour le moment une durée de vie illimitée (vous pouvez donc le mettre dans vos scripts). Il sera proposé plus tard de faire des tokens à durée limitée.
Une fois l'utilisateur authentifié, il sera automatiquement redirigé vers l'URL que vous avez mis dans la création du token (https://www.mywebsite.com/ dans l'exemple précédent).

Il est ainsi possible de faire une application web qui invite l'internaute à s'authentifier chez OVH. Il sera automatiquement redirigé vers votre application web une fois authentifié.

Réaliser votre premier appel à l'API.

.

Signature des requêtes

Maintenant que vous êtes en possession de vos 3 clés (AK, AS, CK), vous pouvez signer une requête vers l'API. Le calcul de signature se fait comme suit :
"$1$" + SHA1_HEX(AS+"+"+CK+"+"+METHOD+"+"+QUERY+"+"+BODY +"+"+TSTAMP)

Si on veut faire par exemple, un GET sur l'adresse https://ca.api.ovh.com/1.0/domains/, la signature avant hashage vaut :
EXEgWIz07P0HYwtQDs7cNIqCiQaWSuHF+MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1+GET+https://ca.api.ovh.com/1.0/domains/++1366560945

Et après hashage :
$1$9517505d8998e66b9d4839b896d3377a53ac8742
.

Gestion du timestamp

Pour éviter les rejeux, vous pouvez remarquer dans le paragraphe précédent que la signature inclut le timestamp actuel.
Afin de pouvoir fonctionner même si votre machine n'est pas à l'heure, vous pouvez récupérer l'heure « OVH » en faisant un GET sur l'URL suivante : https://ca.api.ovh.com/1.0/auth/time

$ curl https://ca.api.ovh.com/1.0/auth/time
1366561236
Vous pouvez ainsi calculer l'écart entre l'heure « OVH » et votre horloge système et l'appliquer lors des signatures.
.

Execution d'une requête

En possession de la signature, vous pouvez faire la requête à l'API. Pour ce faire, il faut rajouter votre clé publique d'application, le token, la date et la signature dans les en-têtes de la requête.
Exemple avec cURL :
$ curl -H 'X-Ovh-Application:7kbG7Bk7S9Nt7ZSV'                   \
-H 'X-Ovh-Timestamp:1366560945'                                  \
-H 'X-Ovh-Signature:$1$9517505d8998e66b9d4839b896d3377a53ac8742' \
-H 'X-Ovh-Consumer:MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1'             \
https://ca.api.ovh.com/1.0/domains/
["ovh.com","ovh.net"]
.

Surcouches sur l'API OVH

OVH vous propose, afin de faciliter le développement de vos applications, des surcouches dans différents langages. Leur utilisation vous permettra de vous affranchir du calcul des signatures et de vous concentrer sur le développement de votre application.