--- title: "OKMS authentication methods" description: "Find out how to configure Personal Access Tokens, service accounts, or access certificates to authenticate to your OKMS domain regional REST API" url: https://docs.ovhcloud.com/en/guides/manage-and-operate/kms/okms-authentication-methods lang: en lastUpdated: 2026-07-16 --- # OKMS authentication methods ## 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](/en/guides/account-and-service-management/account-information/ovhcloud-account-creation.md). - An [OKMS domain](/en/guides/manage-and-operate/kms/quick-start.md) 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](/en/guides/manage-and-operate/api/apiv2.md) 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://.okms.ovh.net/swagger/`, the [OKMS CLI](https://github.com/ovh/okms-cli), or the [Go SDK](https://pkg.go.dev/github.com/ovh/okms-sdk-go). ### Choose your authentication method | Method | Best for | REST API | KMIP | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | | **Personal Access Token (PAT)** | Scripts and automation acting on behalf of a [local user](/en/guides/account-and-service-management/account-information/ovhcloud-users-management.md) | 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** #### Step 1 — Create a local user If you do not have one yet, create an [OVHcloud local user](/en/guides/account-and-service-management/account-information/ovhcloud-users-management.md). #### Step 2 — Create a PAT Create a [Personal Access Token (PAT)](/en/guides/manage-and-operate/iam/configure-personal-access-token-pat.md) on the local user. #### Step 3 — Create an IAM policy Create an [IAM policy](/en/guides/account-and-service-management/account-information/iam-policy-ui.md) that grants the local user the required OKMS actions on your domain. See [IAM rights for OKMS](#iam-rights-for-okms) below. #### Use the PAT on the data plane Send the PAT as a Bearer token: ```bash curl -H "Authorization: Bearer " \ https://eu-west-rbx.okms.ovh.net/v1/servicekey ``` In the [Swagger UI](#use-the-okms-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](/en/guides/manage-and-operate/iam/configure-personal-access-token-pat.md). **Service account** #### Step 1 — Create a service account If you do not have one yet, create an [OVHcloud service account](/en/guides/manage-and-operate/api/manage-service-account.md). #### Step 2 — Create an IAM policy Create an [IAM policy](/en/guides/account-and-service-management/account-information/iam-policy-ui.md) that grants the service account the required OKMS actions on your domain. See [IAM rights for OKMS](#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](/en/guides/account-and-service-management/account-information/authenticate-api-with-service-account.md), then pass it as a Bearer token: ```bash curl -H "Authorization: Bearer " \ https://eu-west-rbx.okms.ovh.net/v1/servicekey ``` In the [Swagger UI](#use-the-okms-swagger-ui), use the **oAuth2ClientCredentials** scheme in the Authorize dialog. **Access certificate** #### 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](/en/guides/manage-and-operate/iam/identities-management.md). #### Step 2 — Create an OKMS certificate Create an OKMS access certificate with at least one identity attached. See [Manage your OKMS access certificate](/en/guides/manage-and-operate/kms/okms-certificate-management.md). #### Step 3 — Create an IAM policy Create an [IAM policy](/en/guides/account-and-service-management/account-information/iam-policy-ui.md) 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](/en/guides/manage-and-operate/kms/kms-kmip.md#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](#use-the-okms-swagger-ui) below. ### Use the OKMS Swagger UI The OKMS domain exposes a unified Swagger UI at `https://.okms.ovh.net/swagger/`. For example, for a domain in **eu-west-rbx**: [https://eu-west-rbx.okms.ovh.net/swagger/](https://eu-west-rbx.okms.ovh.net/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](#set-up-authentication) for your chosen method, including the required [IAM policy](#iam-rights-for-okms), 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 ` 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](/en/guides/account-and-service-management/account-information/authenticate-api-with-service-account.md) 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`): ```bash 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. ![Firefox certificate manager settings](/images/manage-and-operate/kms/kms-usage/firefox-cert-manager.png) - 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. ![Chromium certificate manager](/images/manage-and-operate/kms/kms-usage/chromium-cert-manager.png) ##### Access Swagger with your certificate Open `https://.okms.ovh.net/swagger/` in your browser. You will be prompted to select the imported certificate: ![Browser certificate identification prompt](/images/manage-and-operate/kms/kms-usage/firefox-identify-with-certificate.png) You can now execute API calls interactively from the Swagger UI. ### IAM rights for OKMS OKMS IAM actions follow the pattern `okms::/`: | 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](/en/guides/manage-and-operate/kms/kms-kmip.md#iam-rights) | #### 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 OVHcloud API console under product type **Key Management System (KMS)** , or in [IAM policies](/en/guides/account-and-service-management/account-information/iam-policy-ui.md) when creating a policy. #### Suggested IAM policies Apply these templates to your OKMS domain resource (`urn:v1::resource:okms:`). Replace `` and `` with your values. Create policies via the [Control Panel](/en/guides/account-and-service-management/account-information/iam-policy-ui.md) or the [IAM API](/en/guides/account-and-service-management/account-information/iam-policies-api.md). **Full admin** — full control over the OKMS domain via REST API: ```json { "name": "okms-full-admin", "description": "Full administrative access to an OKMS domain", "identities": [""], "resources": [{ "urn": "" }], "action": ["okms:apiovh:*"] } ``` **Read-only** — list and inspect resources without write or cryptographic operations: ```json { "name": "okms-read-only", "description": "Read-only access to an OKMS domain", "identities": [""], "resources": [{ "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: ```json { "name": "okms-crypto-only", "description": "Cryptographic operations on an OKMS domain", "identities": [""], "resources": [{ "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: ```json { "name": "okms-secret-access-only", "description": "Read-only access to Secret Manager secrets on an OKMS domain", "identities": [""], "resources": [{ "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](/en/guides/manage-and-operate/kms/kms-kmip.md#iam-rights). ::: ## Go further [Using the OVHcloud Key Management Service (KMS) with your data](/en/guides/manage-and-operate/kms/kms-usage.md) [Use Secret Manager with REST API](/en/guides/manage-and-operate/secret-manager/rest-api.md) [How to connect a compatible product using KMIP protocol](/en/guides/manage-and-operate/kms/kms-kmip.md) [Manage your OKMS access certificate](/en/guides/manage-and-operate/kms/okms-certificate-management.md) Join our [community of users](https://community.ovhcloud.com/).