OKMS authentication methods

View as Markdown

Find out how to configure Personal Access Tokens, service accounts, or access certificates to authenticate to your OKMS domain regional REST API

Objective

This guide explains how to authenticate to the OKMS data plane — the regional REST API exposed on your OKMS domain (for example https://eu-west-rbx.okms.ovh.net). This API is shared by Key Management Service (KMS) and Secret Manager.

Three authentication methods are available for the REST API. KMIP integrations support access certificates only — we recommend reserving certificates for KMIP use cases, as they require a more complex setup than tokens.

Requirements

An OVHcloud customer account.
An OKMS domain in the target region (created when ordering KMS or activating Secret Manager in that region).

Instructions

Understand the OKMS data plane

The OKMS data plane is the regional API endpoint for cryptographic operations (KMS) and secret storage (Secret Manager). It is distinct from the centralized OVHcloud API control plane (/v2/okms/...), which manages OKMS domain provisioning and configuration.

Layer	Endpoint example	Purpose
Data plane (regional)	`https://eu-west-rbx.okms.ovh.net`	Encrypt, sign, manage keys and secrets on the domain
Control plane (OVHcloud API)	`https://eu.api.ovh.com/v2/okms/...`	Order domains, manage credentials, configure logging

You can interact with the data plane through the unified Swagger UI at https://<region>.okms.ovh.net/swagger/, the OKMS CLI, or the Go SDK.

Choose your authentication method

Method	Best for	REST API	KMIP
Personal Access Token (PAT)	Scripts and automation acting on behalf of a local user	Supported	Not supported
Service account	Machine-to-machine integrations	Supported	Not supported
Access certificate	KMIP-compatible products, mTLS clients, browser-based Swagger with client certificates	Supported	Required

Tip

For REST API access, prefer a PAT or service account. Reserve access certificates for KMIP or mTLS-based clients.

Set up authentication

Personal Access Token

Service account

Access certificate

Step 1 — Create a local user

If you do not have one yet, create an OVHcloud local user.

Step 2 — Create a PAT

Create a Personal Access Token (PAT) on the local user.

Step 3 — Create an IAM policy

Create an IAM policy that grants the local user the required OKMS actions on your domain. See IAM rights for OKMS below.

Use the PAT on the data plane

Send the PAT as a Bearer token:

curl -H "Authorization: Bearer <your_pat>" \
  https://eu-west-rbx.okms.ovh.net/v1/servicekey

In the Swagger UI, use the personalAccessToken scheme in the Authorize dialog.

If the regional endpoint does not accept the Bearer scheme directly, use hybrid authentication with the pat_jwt_ prefix as described in the PAT guide.

Step 1 — Create a service account

If you do not have one yet, create an OVHcloud service account.

Step 2 — Create an IAM policy

Create an IAM policy that grants the service account the required OKMS actions on your domain. See IAM rights for OKMS below.

Use the service account on the data plane

Obtain an OAuth2 access token using the client-credentials flow as described in How to use service accounts to connect to OVHcloud APIs, then pass it as a Bearer token:

curl -H "Authorization: Bearer <access_token>" \
  https://eu-west-rbx.okms.ovh.net/v1/servicekey

In the Swagger UI, use the oAuth2ClientCredentials scheme in the Authorize dialog.

Step 1 (optional) — Create an identity

If you do not have one yet, create an OVHcloud identity (local user, user group, or service account). See Presentation of identities.

Step 2 — Create an OKMS certificate

Create an OKMS access certificate with at least one identity attached. See Manage your OKMS access certificate.

Step 3 — Create an IAM policy

Create an IAM policy that grants the identities linked to the certificate access to your OKMS domain.

For REST API access, use the okms:apiovh:* actions listed below.
For KMIP access, grant the okms:kmip:* actions documented in KMIP IAM rights.

Use the certificate on the data plane

Present the client certificate over TLS (mTLS). For browser-based Swagger access, see Use the OKMS Swagger UI below.

Use the OKMS Swagger UI

The OKMS domain exposes a unified Swagger UI at https://<region>.okms.ovh.net/swagger/. For example, for a domain in eu-west-rbx: https://eu-west-rbx.okms.ovh.net/swagger/.

You can also open it from the Swagger link on your .

The Swagger UI supports all three REST API authentication methods. Complete the setup steps for your chosen method, including the required IAM policy, before executing requests.

Personal Access Token

Click the Authorize button (lock icon) in the Swagger UI.
Under personalAccessToken (HTTP Bearer, JWT format), paste the PAT you created for your local user.
Click Authorize, then Close.

Swagger sends your token as an Authorization: Bearer <token> header on every request you execute.

Service account

Click the Authorize button in the Swagger UI.
Under oAuth2ClientCredentials, enter your service account client_id and client_secret. See How to use service accounts to connect to OVHcloud APIs to obtain these credentials.
Swagger obtains an OAuth2 access token using the client-credentials flow and attaches it to subsequent requests.

Access certificate

Access certificate authentication uses mutual TLS (mTLS) at the transport layer. The certificate is presented by your browser when connecting to the Swagger URL — it is not configured through the Authorize dialog.

Import your certificate into the browser

Convert your OKMS certificate and private key to PKCS#12 format (assuming files named ID_certificate.pem and ID_privatekey.pem):

openssl pkcs12 -export -in ID_certificate.pem -inkey ID_privatekey.pem -out client.p12

You will be prompted to set a password for the encrypted file. Import client.p12 into your browser:

On Firefox

Type about:preferences#privacy into the address bar.
Scroll down to the Certificates section.

Click View Certificates..., open the My Certificates tab, then Import... and select your client.p12 file.
Enter the PKCS#12 password when prompted.

On Chrome/Chromium

Type chrome://settings/certificates into the address bar.
Open the Your certificates tab, click Import, and select your client.p12 file.
Enter the PKCS#12 password when prompted.

Access Swagger with your certificate

Open https://<region>.okms.ovh.net/swagger/ in your browser. You will be prompted to select the imported certificate:

Browser certificate identification prompt

You can now execute API calls interactively from the Swagger UI.

IAM rights for OKMS

OKMS IAM actions follow the pattern okms:<channel>:<resource>/<operation>:

Channel	Scope	Used for
`okms:apiovh`	Control plane and data plane REST API	KMS keys, secrets, certificates, domain configuration
`okms:apikms`	Regional data plane REST API	Direct regional API calls (some integrations use both `apiovh` and `apikms` actions)
`okms:kmip`	KMIP protocol	KMIP-compatible product integrations — see dedicated documentation

Common `okms:apiovh` actions

Action	Description
`okms:apiovh:serviceKey/get`	List or retrieve encryption keys
`okms:apiovh:serviceKey/create`	Create or import a key
`okms:apiovh:serviceKey/update`	Update key metadata
`okms:apiovh:serviceKey/delete`	Delete a key
`okms:apiovh:serviceKey/activate`	Activate a key
`okms:apiovh:serviceKey/deactivate`	Deactivate a key
`okms:apiovh:serviceKey/encrypt`	Encrypt data with a key
`okms:apiovh:serviceKey/decrypt`	Decrypt data with a key
`okms:apiovh:serviceKey/sign`	Sign data with a key
`okms:apiovh:serviceKey/verify`	Verify a signature
`okms:apiovh:serviceKey/datakey`	Generate a data key
`okms:apiovh:serviceKey/datakeyDecrypt`	Decrypt a data key
`okms:apiovh:secret/get`	List secrets and metadata
`okms:apiovh:secret/create`	Create a secret
`okms:apiovh:secret/update`	Update secret metadata
`okms:apiovh:secret/delete`	Delete a secret
`okms:apiovh:secret/version/getData`	Read secret version content
`okms:apiovh:credential/get`	List access certificates
`okms:apiovh:credential/create`	Create an access certificate
`okms:apiovh:credential/delete`	Delete an access certificate
`okms:apiovh:secretConfig/get`	Read Secret Manager default configuration
`okms:apiovh:secretConfig/update`	Update Secret Manager default configuration

Info

Listing a secret version (okms:apiovh:secret/get) is separate from reading its content (okms:apiovh:secret/version/getData). Grant both when the identity must read secret values.

Browse the full action list in the under product type Key Management System (KMS), or in IAM policies when creating a policy.

Suggested IAM policies

Apply these templates to your OKMS domain resource (urn:v1:<region>:resource:okms:<okmsId>). Replace <identity_urn> and <okms_urn> with your values. Create policies via the Control Panel or the IAM API.

Full admin — full control over the OKMS domain via REST API:

{
  "name": "okms-full-admin",
  "description": "Full administrative access to an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": ["okms:apiovh:*"]
}

Read-only — list and inspect resources without write or cryptographic operations:

{
  "name": "okms-read-only",
  "description": "Read-only access to an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:serviceKey/get",
    "okms:apiovh:secret/get",
    "okms:apiovh:credential/get",
    "okms:apiovh:secretConfig/get",
    "okms:apiovh:log/get"
  ]
}

Add okms:apiovh:secret/version/getData if the identity must read secret values.

Cryptographic operations only — use keys for encrypt, decrypt, sign, and verify without managing keys or secrets:

{
  "name": "okms-crypto-only",
  "description": "Cryptographic operations on an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:serviceKey/get",
    "okms:apiovh:serviceKey/encrypt",
    "okms:apiovh:serviceKey/decrypt",
    "okms:apiovh:serviceKey/sign",
    "okms:apiovh:serviceKey/verify",
    "okms:apiovh:serviceKey/datakey",
    "okms:apiovh:serviceKey/datakeyDecrypt"
  ]
}

Secret access only — read Secret Manager secrets without access to KMS keys, certificates, or domain configuration:

{
  "name": "okms-secret-access-only",
  "description": "Read-only access to Secret Manager secrets on an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:secret/get",
    "okms:apiovh:secret/version/getData",
    "okms:apikms:secret/version/getData"
  ]
}

Add okms:apiovh:secret/create, okms:apiovh:secret/update, and okms:apiovh:secret/delete if the identity must manage secrets.

Warning

KMIP operations use okms:kmip:* actions, not okms:apiovh:*. Certificate-based KMIP access requires both certificate creation and the KMIP IAM rights from the KMIP guide.