Exoscale offers you multiple ways to interact with the platform in a programmatic way, from either a command line, your favourite programming language, or some of our integrations to 3rd party tools.

To do so you have first to obtain either a Personal Key or an Exoscale API Key.

Personal Keys

Personal Keys are specific to your user account and the organization you are in. In other words, your colleagues within the same Organization will have different keys than you, and you will have a different key per organization you are in.

Personal Keys are generated by default when you create an organization or access one for the first time. To find your Personal Key key for a given Organization:

  1. Ensure you are in the proper context using the Organization dropdown on the top right
  2. go to Account -> Profile -> API Keys.

Remember that personal API Keys are tied to your user account, so your API Key will have the same permissions as your user has within the organization.

Personal Keys are a convenient quick setup with low granularity to get you started with CLI or to explore the API. For production grade deployments and any real-world programmatic usage you should use API Keys.

API Keys

API Keys are independent of your user account and have the benefit of fine grained permission controls.

You can create API Keys either from the UI or the exo CLI.

The following example shows you how to create such API Key using the exo CLI, and assume you’ve configured the CLI previously with your Personal Key.

Create a new API Key:

exo iam apikey create yourapikey

This will create an unrestricted API Key that can use all operations.

However, for most use cases it is advisable to create a restricted API Key that can only be used for certain operations. This can be achieved by passing the --operation parameter.

The following example restricts the new API Key to the Compute service:

exo iam apikey create your-compute-key --operation "compute/*"

Multiple operations can be passed separated by commas. The following example also showcases how you can specify single commands under a service:

exo iam apikey create my-restricted-key --operation "compute/listZones,iam/listApiKeys"

To list the complete list of possible operations:

exo iam apikey operations

Consequently, API keys can be listed with:

exo iam apikey list

API Keys can be revoked, once revoked they cannot be recovered. To revoke a key:

exo iam apikey revoke EXO...

It is worth noting though that there is no way to update an API key, they are immutable by design. If you want to change an API key, you will need to generate a new one.

To ease the process for complex keys, you can take advantage of the “Use as a Template” functionality on the web application: this will use an existing key restrictions to populate the creation view, so you can reduce the amount of work needed in creating identical or slightly modified keys.

About Async Commands

Be aware that by restricting an Api Key on commands that execute asynchronously, you will not be able to use that same key to query the result of the action unless you give access to the queryAsyncJobResult command.

Be also aware that queryAsyncJobResult may contain sensitive information (e.g. Instance details including passwords, immediately after creation and until purge of the job queue).