First Steps with the OVHcloud API

The OVHcloud API is a great way to manage your services with OVHcloud, offering even more features than the OVHcloud Manager. In this article, we will cover how to use the OVHcloud API.

Topics

• Creating Identifiers
• Using the API for the First Time

Creating Identifiers

Creation of Your Application Keys

Authentication consists of two keys. The first is the application key. Any application wanting to communicate with the OVHcloud API must be declared in advance.

Click on the following link: https://api.us.ovhcloud.com/createApp/, enter your customer ID, password, and the name of your application. The name will be useful later if you want to allow others to use it.

You will get two keys:

• the application key, named "AK", e.g.:

7kbG7Bk7S9Nt7ZSV

• the secret application key, named "AS", e.g.:

EXEgWIz07P0HYwtQDs7cNIqCiQaWSuHF

Requesting an Authentication Token from OVHcloud

Now that you have your keys, you can request a token from OVHcloud to enable you to make requests to the API. To do so, go to https://api.us.ovhcloud.com/1.0/auth/credential to specify the access you require. In our example, we will request an OVHcloud read-only token for the entire API.

cURL example:

$ 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"}

Connect the Authentication Token to an OVHcloud Customer Account

In the response, you will be sent a validation URL and a consumerKey (the token named CK). This token is not initially linked to any customer. You (or another customer) will connect your OVHcloud account to this token by logging in using the URL.

This stage will enable you to identify any OVHcloud customer and obtain rights on their account. This could be useful if you want to develop an app for the community. Otherwise, you can log in directly on this page.

For the time being, this token has an unlimited lifespan (so you can put it in your scripts). Limited lifespan tokens will be offered at a later stage. Once the user has been authenticated, they will be automatically redirected to the URL you entered when the token was created (https://www.example.com/ in the previous example).

You can then make a web application that invites internet users to undergo OVHcloud authentication. They will be automatically redirected to your application once they have been authenticated.

Using the API for the First Time

Signing Requests

Now that you have your three keys (AK, AS, CK), you can sign requests made to the API. The signature is calculated as follows:

"$1$" + SHA1_HEX(AS+"+"+CK+"+"+METHOD+"+"+QUERY+"+"+BODY+"+"+TSTAMP)

For example, if you carry out a GET command command on the address https://api.us.ovhcloud.com/1.0/domains/, the pre-hash signature is:

EXEgWIz07P0HYwtQDs7cNIqCiQaWSuHF+MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1+GET+https://api.us.ovhcloud.com/1.0/domains/++1366560945

And post-hash:

$1$d3705e8afb27a0d2970a322b96550abfc67bb798

Managing Timestamps

To avoid replay, you can see that the signature includes the current timestamp in the preceding paragraph.

In order to function properly, even if your machine is not up to date, you can retrieve the "OVHcloud" time carrying out a GET on the following URL: https://api.us.ovhcloud.com/1.0/auth/time

$ curl https://api.us.ovhcloud.com/1.0/auth/time
1366561236

You can also calculate the time lag between "OVHcloud" time and your system clock and apply this to the signatures.

Carrying Out a Request

Once you have the signature, you can make a request to the API. To do this, add your public application key as well as the token, date, and signature to the request header.

cURL example:

$ curl -H 'X-Ovh-Application:7kbG7Bk7S9Nt7ZSV'                   \
-H 'X-Ovh-Timestamp:1366560945'                                  \
-H 'X-Ovh-Signature:$1$d3705e8afb27a0d2970a322b96550abfc67bb798' \
-H 'X-Ovh-Consumer:MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1'             \
https://api.us.ovhcloud.com/1.0/domains/
["ovhcloud.com","ovh.us"]

Wrappers on OVHcloud API

In order to simplify the development of your applications, OVHcloud provides you with wrappers in several languages. Using them will allow you to not concern yourself with the signature calculation, and instead focus on the development of your application.

• Perl: https://api.us.ovhcloud.com/wrappers/OvhApi-perl-1.1.zip
• Python: https://github.com/ovh/python-ovh
• PHP: https://github.com/ovh/php-ovh
• Node.js: https://github.com/ovh/node-ovh
• Swift: https://github.com/ovh/swift-ovh
• C#: https://github.com/ovh/csharp-ovh

Conclusion

Having read this article, you should be able to complete some basic steps to more efficiently leverage the OVHcloud API on your OVHcloud services.