Key stores

Create key store

POST/v4/config/ows/key-management/key-stores

Adds a key store of a provider to the organisation, so that the wallet can create, reference or sign with keys in it. Get the provider ID and its type from List key store types. The organisation can add at most one key store of each provider, and never a local key store (every organisation already uses the key store of the installation).

`type`	Key store	Connection test
`vault`	An external OpenBao or HashiCorp Vault (Transit)	Log in, read the health of the vault, list the Transit keys.
`gcp-kms`	A key ring in Google Cloud KMS	List the keys of the key ring.
`aws-kms`	One region of AWS KMS	List the keys of the region.
`azure-key-vault`	An Azure key vault or managed HSM	Get an application token from Microsoft Entra ID, list the keys.
`dpod`	A Thales Luna Cloud HSM partition	Give the partition to the HSM signer, wait (at most 90 seconds) until it is active, then sign and verify with a session key.
`csc`	A remote signing key store (the CSC API of a QTSP)	Get an OAuth 2.0 token, list the credentials.

The wallet checks the settings and the credentials, then runs the connection test, and saves the key store only when the test passes (a dpod key store that fails its test is deleted again). A missing permission at the provider gives The connection test failed: Key management service refused the request. The wallet refuses an address in a private network unless the installation allows private addresses, and the cloud KMS types call only the official endpoints of the provider.

The credentials are write-only: no answer returns them. A call with a sandbox API key adds the key store to the main organisation.

Create key store

Language of the request sample

ExampleExample request

curl -X POST 'https://demo-api.igrant.io/v4/config/ows/key-management/key-stores' \
  -H 'Authorization: ApiKey <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "vault",
  "provider": "openbao",
  "name": "Customer OpenBao",
  "settings": {
    "address": "https://openbao.example.com:8200",
    "namespace": null,
    "transitMount": "transit",
    "authentication": {
      "method": "approle",
      "roleId": "<yourRoleId>"
    }
  },
  "credentials": {
    "secretId": "<yourSecretId>"
  }
}'

{
  "id": "local-openbao",
  "type": "local",
  "provider": null,
  "name": "Local vault",
  "local": true,
  "status": "active",
  "protection": "software",
  "settings": {},
  "credentialsConfigured": {},
  "capabilities": [
    "create",
    "import",
    "sign",
    "csr",
    "certificateChain",
    "test"
  ],
  "qscd": false,
  "keyCount": 3,
  "retiredKeyCount": 0,
  "qualifiedStatus": null,
  "lastCheckedAt": null,
  "lastCheckResult": {
    "ok": true,
    "message": null,
    "checkedAt": "2026-10-20T10:05:00Z"
  },
  "createdAt": "2026-10-20T10:00:00Z",
  "updatedAt": "2026-10-20T10:00:00Z"
}

Authorizations

Authorizationstringheaderrequired
Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.
Scope:keys:create

Body

application/json

The type, the provider, the name, the settings and the credentials of the key store.

typeenum<string>required
The key store type. It must be the type of the provider.
Available options:vault,gcp-kms,aws-kms,azure-key-vault,dpod,csc
Example:"vault"
providerstringrequired
The provider, an id of providers in List key store types. It cannot change later.
At most 64 characters.
Example:"openbao"
namestringrequired
The name of the key store, unique in the organisation, at most 100 characters.
At most 100 characters.
Example:"Customer vault"
settingsobjectrequired
The settings of the type (the schema of the same title). The wallet refuses an unknown member and checks the format of each value, for example the AWS region or the Azure vault URL.
credentialsobject
The write-only credentials of the type (the schema of the same title). Give the credentials that the settings use; for vault and azure-key-vault, those of the authentication method.

Response

application/json

The key store, saved after a passed connection test.

idstring
The key store ID. local-openbao or local-hsm for a local key store of the installation, else a UUID.
Example:"local-openbao"
typeenum<string>
The key store type. local: a key store of the installation (OpenBao Transit or the HSM of the installation); every organisation can use it, and the API cannot add, change or delete it. vault: an external OpenBao or HashiCorp Vault. gcp-kms: a key ring in Google Cloud KMS. aws-kms: one region of an AWS account. azure-key-vault: an Azure key vault or managed HSM. dpod: a partition of a Thales Luna Cloud HSM service (DPoD). csc: a remote signing key store, which signs through the Cloud Signature Consortium (CSC) API of a QTSP.
Available options:local,vault,gcp-kms,aws-kms,azure-key-vault,dpod,csc
Example:"local"
providerstring | null
The provider of the key store, an id from List key store types, for example openbao, hashicorp-vault, google-cloud-kms or intesi. null for a local key store. It cannot change.
namestring
The name of the key store, unique in the organisation. A local key store is Local vault (local-openbao). On an installation with the HSM as a dedicated option, the organisation has two local key stores that take new keys: Local vault (HSM) (local-hsm, the default key store of a new key) and Local vault (OpenBao) (local-openbao, the key store of an import that names no key store).
At most 100 characters.
Example:"Local vault"
localboolean
true for a key store of the installation (type local).
Example:true
statusenum<string>
active: the last connection test passed, or the key store is not tested yet. error: the last connection test failed (a new dpod key store also has error until its first test passes). disabled is not in use.
Available options:active,disabled,error
Example:"active"
protectionenum<string> | null
Where the private keys of the key store are. software: in the software of a key management service (local with openbao, vault, gcp-kms with SOFTWARE, azure-key-vault with EC). hsm: in the HSM of the installation (local with hsm). hsm-backed: in a cloud KMS that keeps the keys in hardware security modules (gcp-kms with HSM, aws-kms, azure-key-vault with EC-HSM). dedicated-hsm: in an HSM partition of the organisation (dpod). provider: at the QTSP, which decides (csc).
Available options:software,hsm,hsm-backed,dedicated-hsm,provider
Example:"software"
settingsobject
The settings of the key store type, with the defaults filled in. Never a secret.
credentialsConfiguredobject
Each credential member of the key store type, with true when the wallet has a value for it. The answer never has the value. Empty for a local key store. For example password, secretId, token and clientPrivateKey for vault, or clientSecret and userPin for csc.
capabilitiesenum<string>[]
What the key store can do. create: Create key. import: Import key. reference: sign with a key that the provider already has. sign: sign with its keys. csr: make a CSR. certificateChain: store a certificate chain on a key. listProviderKeys: List provider keys. test: Test key store. edit and delete: change and delete the key store. A local key store has create and import only when it takes the new keys (no import with the HSM backend). A csc key store has no create, import, csr or certificateChain: the QTSP keeps the keys and gives the certificates.
Available options:create,import,reference,sign,csr,certificateChain,listProviderKeys,test,edit,delete
qscdany
Whether the key store keeps the keys in a qualified signature or seal creation device (QSCD). false, or provider for csc, where the QTSP decides.
Example:false
keyCountinteger
The number of keys of the organisation in the key store, without the retired keys.
Example:3
retiredKeyCountinteger
The number of retired keys of the organisation in the key store. A retired key stays in its key store as evidence until the organisation is purged, so Delete key store needs keyCount and retiredKeyCount both at 0.
Example:0
qualifiedStatusenum<string> | null
For a key store of a provider with qualified true only: qualified when the key store has keys and each of them is qualified (trust of the key), not-qualified when one is not, else unknown. null for every other key store.
Available options:qualified,not-qualified,unknown
lastCheckedAtstring | null
When the last connection test ran (ISO 8601 date-time, UTC). null before the first test.
lastCheckResultobject | null
The result of the last connection test. null before the first test.
createdAtstring | null
When the key store was added (ISO 8601 date-time, UTC).
Example:"2026-10-20T10:00:00Z"
updatedAtstring | null
When the key store last changed (ISO 8601 date-time, UTC).
Example:"2026-10-20T10:00:00Z"