Clever Cloud API Overview

The Clever Cloud Console and Clever Tools allow you to manage your account and products with the same public API you can use for your own services and integrations. This article will explain how to connect to this API and use it.

Request the API

Clever Cloud’s REST API offers two authentication mechanisms to meet different integration needs:

• API tokens provide a straightforward way to authenticate requests on behalf of a specific user. These tokens operate similarly to passwords and should be handled with appropriate security measures. API tokens are ideal for personal scripts, CLI tools, and scenarios where you’re accessing your own resources.

• OAuth 1 is designed for third-party applications that need to access Clever Cloud resources on behalf of their users. This authentication flow allows applications to request permissions from users without requiring direct access to their credentials. OAuth 1 is recommended for public applications, services that integrate with multiple user accounts, or any scenario where user delegation is required.

Choose the authentication method that best aligns with your specific integration requirements and security considerations.

API tokens

From Clever Tools

To create a token, you can use Clever Tools. This feature needs to be enabled:

clever features enable tokens
clever tokens create "CI job Foobar"
clever tokens create "Quick local test" --expiration 1h

You can also list or revoke tokens:

clever tokens -F json
clever tokens revoke api_tokens_xxx

Once created, API tokens must be used through the bridge URL:

curl https://api-bridge.clever-cloud.com/v2/self -H "Authorization: Bearer [API_TOKEN]"

clever curl

clever curl is a wrapper around curl, it supports the same arguments and handles the authentication automatically for you using the CLI account you’re currently logged in with. It’s a simple way to make requests to the Clever Cloud API if Clever Tools are installed on your system.

clever curl https://api.clever-cloud.com/v2/self
clever curl https://api.clever-cloud.com/v2/summary
clever curl https://api.clever-cloud.com/v4/products/zones
clever curl https://api.clever-cloud.com/v2/organisations/<ORGANISATION_ID>/applications | jq '.[].id'
clever curl https://api.clever-cloud.com/v4/billing/organisations/<ORGANISATION_ID>/<INVOICE_NUMBER>.pdf > invoice.pdf

Official clients/SDKs

You can request the Clever Cloud API from multiple languages through our official clients/SDKs:

• Go
• JavaScript
• Rust

OAuth1

If you have an application that needs to access Clever Cloud resources on behalf of your users, you can use OAuth1. This is the recommended way to authenticate third-party applications.

Create an OAuth consumer

First, you’ll need to create an OAuth consumer for your application. This can be done in the Clever Cloud console. Go to your organization, click on Create…, then on an OAuth consumer and fill the form. You will get a consumer key and a consumer secret for your application.

Integrate your application

Your application must implement the OAuth 1 dance. It mostly consists of the following steps:

• Get a “request token”
  • POST /oauth/request_token
  • You will get a temporary oauth_token and oauth_token_secret
• Redirect the user to the authorization page with the oauth_token
  • GET /oauth/authorize
  • Once the user is logged in, the browser will be redirected to your application with the query params oauth_verifier and oauth_token
• Make sure the oauth_token from the first step matches the one you get after the redirection
• Get the “access token” with the oauth_token, oauth_token_secret and oauth_verifier
  • POST /oauth/access_token
  • You will get the user oauth_token and oauth_token_secret

Once done, your application can make API requests on behalf of the user with an OAuth 1 compatible client and the following tokens:

• Consumer key
• Consumer secret
• User token
• User token secret

More information about OAuth dance.

About the OAuth1 signature

There are 3 supported methods for the signature: PLAINTEXT, HMAC-SHA1 and HMAC-SHA512. While PLAINTEXT is way easier, HMAC-SHA512 ensures that the request is totally verified. The Authorization header must start with OAuth, with a specific format for key/values:

Authorization: OAuth key="value", key2="value2"