OKMS authentication methods

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://us-east-vin.okms.ovh.us). 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.

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

Choose your authentication method

Set up authentication

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

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

Use the OKMS Swagger UI

The OKMS domain exposes a unified Swagger UI at https://<region>.okms.ovh.us/swagger/. For example, for a domain in us-east-vin: https://us-east-vin.okms.ovh.us/swagger/.

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

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

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

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

Service account

1. Click the Authorize button in the Swagger UI.
2. 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.
3. 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:

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>:

Domain management actions on OVHcloud API v2

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

Actions for the KMS regional API

Browse the full action list in the regional Swagger UI at https://<region>.okms.ovh.net/swagger/ or in IAM policies when creating a policy.

Example IAM policies

Apply these templates to your OKMS domain resource. Its URN is displayed in the General information tab of your OKMS domain dashboard. 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:*", "okms:apikms:*"]
}

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:apikms:serviceKey/get",
    "okms:apikms:secret/get",
    "okms:apikms:secretConfig/get"
  ]
}

Add okms:apiovh:secret/version/getData (OVHcloud API v2) or okms:apikms:secret/version/getData (KMS regional API) if the identity must be able to 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:apikms:serviceKey/get",
    "okms:apikms:serviceKey/encrypt",
    "okms:apikms:serviceKey/decrypt",
    "okms:apikms:serviceKey/sign",
    "okms:apikms:serviceKey/verify",
    "okms:apikms:serviceKey/dataKey/create",
    "okms:apikms:serviceKey/dataKey/decrypt"
  ]
}

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/get",
    "okms:apikms:secret/version/getData"
  ]
}

To manage secrets via the OVHcloud API v2, add okms:apiovh:secret/create, okms:apiovh:secret/edit, okms:apiovh:secret/updateMetadata, and okms:apiovh:secret/delete. To manage them via the KMS regional API, add okms:apikms:secret/create, okms:apikms:secret/updateMetadata, and okms:apikms:secret/delete.

Go further

Using the OVHcloud Key Management Service (KMS) with your data

Use Secret Manager with REST API

How to connect a compatible product using KMIP protocol

Manage your OKMS access certificate