Skip to content

Authentication

Every call is authenticated by a bearer token. The token belongs to one of your account's identities, and IAM decides what that identity may do.

View as Markdown (opens in a new tab)
Agent setup

The header

The token goes in the authorization header, as a bearer credential. Every sample on this site sends it this way:

$ curl https://api.eu.ovhcloud.com/v1/me \
  -H "authorization: Bearer $OVH_TOKEN"

Identities

An OVHcloud account holds two kinds of identities, each with its own credentials:

Local users
Identities you create for the people of your company, from Identity, Security & Operations › Identities › Local users. A user signs in as 1234-567-89/johnsmith: its group (Read-Only, Restricted Admin, Administrator) sets a default level of rights, and IAM policies refine it. Creating and managing local users
Service accounts
Identities for scripts and machines, with an OAuth2 client ID and secret. They hold no right of their own: an IAM policy names the service account, the resources and the actions it is allowed. Using service accounts with the API

A personal access token

A personal access token (PAT) lets a local user call the API without its password: a bearer token, with the rights of that user. It does not expire unless you set a date, it is shown once, and deleting it revokes it at once.

Create one in the EU Console, with the API, or with the CLI:

$ ovhcloud iam user token create 1234-567-89/johnsmith --name pat-my-script

With the API, POST /me/identity/user/{user}/token returns the token in its answer. Configuring a personal access token

A service account

A service account authenticates with a client ID and a client secret. Give both to the tool that calls the API, such as the CLI, the Terraform provider or one of the SDKs, and it takes care of the rest: it exchanges them for an access token, sends that token with each call and renews it when it expires. You never handle the token yourself.

The CLI and the Terraform provider both read them from ~/.ovh.conf:

[default]
endpoint = ovh-eu

[ovh-eu]
client_id     = <client id>
client_secret = <client secret>

Keep the secret out of your code and your repositories: store it in this file, in environment variables or in a secret manager. Using service accounts with the API

Get a token without a tool

To call the API with plain HTTP, request a token from the OAuth2 token endpoint yourself, with the client credentials flow:

$ curl -X POST https://www.ovh.com/auth/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=<client id> \
  -d client_secret=<client secret> \
  -d scope=all

The response's access_token is the bearer token to send in the authorization header. It is valid for about an hour: request a new one when it expires.

An application acting for a user

Reading the OAuth2 endpoints…

Rights

Every operation requires an IAM action, listed in its Try it panel. An identity that lacks it gets a 403 with User not granted for this request: grant the action to the identity in an IAM policy, on the resources it may touch.

Public operations

A few operations need no token at all: availability lists, public catalogues. The reference marks each one Public, and each section header says how many it holds.