Getting Started
Deploy DuoKey OpenAI EKM and register your first external key
Overview
Setting up OpenAI EKM has two phases: deploying the app in DuoKey Cockpit (a short, three-step wizard), then registering one or more external keys against a KEK you control in your own cloud KMS.
The first three steps happen once, in DuoKey Cockpit. The last four repeat for every KEK you register.
Prerequisites
Prérequis
- Your OpenAI organization ID (org-…), found at platform.openai.com > Settings > Organization > General
- An organization Admin API key (not a regular project API key) from platform.openai.com > Settings > Organization > Admin keys
- A KEK already created, or the ability to create one, in AWS KMS, Azure Key Vault, or Google Cloud KMS
- Permission to edit IAM policies / role assignments / Workload Identity Federation on that cloud account
Step 1: Start the Wizard
- From the DuoKey Dashboard, open Apps and click + Create new app
- Select OpenAI EKM from the application catalog
Step 2: Organization
App name and organization ID
- App Name — a name for this app, e.g.
OpenAI EKM. - Description — optional free text.
- OpenAI Organization ID — your organization's
org-…id, found at platform.openai.com > Settings > Organization > General.
Step 3: Admin API Key
Provide the Admin API key
- Organization Admin API Key — an Admin key (not a regular API key) from platform.openai.com > Settings > Organization > Admin keys. It is stored sealed by the tenant secret backend and is never returned by the API once saved.
- API Base URL — optional; leave empty to use the default OpenAI API. Only HTTPS URLs to public hosts are accepted.
Step 4: Review & Deploy
Review the app name, organization ID, and API base URL, then deploy. After deployment, open the app to register external keys and follow the per-provider grant instructions.
Step 5: Register Your First External Key
Choose a provider
From the app page, start registering a key and choose which cloud hosts your KEK: AWS KMS, Azure Key Vault, or Google Cloud KMS.
Apply the grant on your cloud KMS
Open the provider's setup instructions from the app — they include your organization id already filled in — and apply the grant before registering:
| Provider | What to configure |
|---|---|
| AWS KMS | Append the provided key policy statement to your KEK's policy. It allows OpenAI's EKM IAM role to call kms:Encrypt / kms:Decrypt, conditioned on sts:ExternalId matching your organization id. |
| Azure Key Vault | Create the OpenAI service principal in your directory, create an RSA key named <org-id>--<name> in your vault, then assign it the Key Vault Crypto User role on the key itself (not the vault). |
| Google Cloud KMS | Create a Workload Identity Federation pool and OIDC provider with the audience set to your organization id, then grant the federated principal roles/cloudkms.cryptoKeyEncrypterDecrypter on your KEK. |
Register the key
Enter the key's coordinates (e.g. the KMS key ARN for AWS, or the vault URI and key name for Azure) and submit. DuoKey submits the registration to OpenAI's Management API. On success the key's status becomes registered and OpenAI assigns it an external key id; on rejection the key stays in an error state with the reason so you can fix the grant and retry.
Activate on your OpenAI projects
Once registered, activate the key on the relevant OpenAI projects from the OpenAI side, per OpenAI's EKM instructions.
You can optionally link a reference key in your DuoKey vault to a registered external key for your own traceability. DuoKey does not use that key cryptographically — the actual KEK stays in your cloud KMS.
After Deployment
Once a key is registered and active, OpenAI calls your cloud KMS directly whenever it needs to wrap or unwrap its Data Encryption Keys with your KEK — DuoKey is not in that call path. From the app page you can:
| Action | Effect |
|---|---|
| Validate a key | Re-checks with OpenAI whether the key is still present in your organization's external key list, and updates its status. |
| Test connectivity | Confirms the stored Admin API key can still reach the OpenAI Management API. |
| Rotate the Admin API key | Replace the stored key without losing existing key registrations. |
| De-register a key | Best-effort removal from OpenAI, then removes the local record. |
Revoking the registration in DuoKey does not, by itself, stop OpenAI from using the key — the grant lives on your cloud KMS. To cut OpenAI's access, remove the IAM permission, role assignment, or Workload Identity Federation binding you created on your KMS. Per OpenAI's EKM design, this takes effect within about an hour.