Key Management - Signing Keys and Certificates
The Organisation Wallet Suite signs everything that your organisation sends to wallets with your own keys: credentials, status lists, verification requests and signed issuer metadata. This guide shows you how to add a key store, create or bring a key, get a certificate for it that wallets trust, and manage your keys.
The flow has three parts:
- Keep the key: every organisation starts with the local vault. You can also add your own vault, a cloud KMS, an HSM or a qualified trust service provider (QTSP) as a key store (Steps 2 to 4).
- Certify the key: a key needs an X.509 certificate chain before it can sign. Request a certificate from your CA with a certificate signing request (CSR), or use the built-in test CA for development (Step 5).
- Get trusted: register the certificate, or its CA, on a trust list so that wallets show your organisation as trusted (Step 6).
For every field and response, see the Key Management API reference.
Step 1: Get the API Key
To obtain your API key, sign in to the dashboard and go to Account > Developer APIs > Create API Key (see Get API Keys). Once you have your API key, enter it in the field below and click the Set API Key button to save it for future use.
Each step below shows a request and an example response. When you click Run, the request runs against your organisation and the example is replaced with the real response. If a request has an ID in its path, such as keyStoreId or keyId, there is a field for it above the request: the step that returns the ID fills it in automatically, or you can paste your own.
In the dashboard, key management starts at Issuer & Verifier > Base Configurations > Key Management and Signing > Configure.
Sandbox organisations share the key stores and keys of their main organisation. From a sandbox organisation, or with a sandbox organisation's API key, you can still create, change and delete these key stores and keys, generate a CSR, upload a certificate chain and use the test CA, but each change applies to the main organisation and all its sandbox organisations.
Step 2: Add a Key Store (optional)
You need this step only if your keys must be kept outside the local vault.
- Check which providers you can add with List Key Store Types.
- Add the key store with Create Key Store, giving its type, provider, settings and credentials. Select an example below, replace the values with your own, and click Run. The API reference describes every field for each type.
Request
Response
Example- The wallet tests the connection and saves the key store only if the test passes. You can repeat the test at any time with Test Key Store. A failed test still returns
200, withokset tofalseand the reason inmessage.
Request
Response
ExampleIn the dashboard, click Configure next to the provider. Test Connection runs the test again.
Credentials are write-only and are never returned. To change a key store, use Update Key Store: any credentials that you leave out are kept, and the provider cannot be changed. To remove a key store that has no keys, use Delete Key Store. A deleted key is retired but stays in its key store until the organisation is purged, so a key store with retired keys cannot be removed; retiredKeyCount shows how many it has. When you delete a key, the wallet destroys its private key in your key store (see Delete a key below).
If you use a cloud KMS, give the wallet's account only the rights it needs.
Thales Luna Cloud HSM (DPoD)
- In DPoD, create the Luna Cloud HSM service and download its service client package (add and configure a client).
- Initialise the partition and the Crypto Officer role with
lunacmfrom the package, as described in the DPoD documentation. - Copy
AuthTokenConfigURI,AuthTokenClientIdandAuthTokenClientSecretfromChrystoki.confin the package. In the dashboard, Fill In from Chrystoki.conf reads them from the file in your browser, without uploading the file. - Add the key store with the partition label, these three values and the Crypto Officer PIN.
New keys are created in the partition as non-extractable key pairs with the label ows:<keyId>.
Step 3: Create a Key
To create a key, run the code block below using the Run button, or call Create Key yourself. Without keyStoreId, the key goes into the local vault (Local vault (HSM) when your installation has two); add keyStoreId to use a key store that you added, and a name that describes what the key is for. The keyId in the response is autofilled in the next steps.
Request
Response
ExampleNew keys are non-exportable ECDSA P-256 keys (ES256). Every key store type except remote signing (csc) can create keys. In the dashboard, click View Keys on a key store, then Create Signing Key.
Step 4: Reference or Import a Key (instead of Step 3)
Use a key that your provider already has. Find its providerKeyName with List Provider Keys, which also shows each public key (jwk) so that you can match it against your provider's console. Then call Create Key with keyStoreId and providerKeyName. A QTSP key comes with its certificate, so you can skip Step 5. In the dashboard, this is Add Existing Key.
Request
Response
ExampleImport a key that you already have. Use Import Key with a password-protected P-256 private key: a PKCS#12 file (.p12 or .pfx) or an encrypted PKCS#8 key in PEM (BEGIN ENCRYPTED PRIVATE KEY). If the file also contains the certificate chain, the key can sign with x509 straight away. You can import into an external vault, and into the local vault backed by OpenBao (local-openbao, shown as Local vault (OpenBao) when your installation has two local vaults); an import without keyStoreId goes there. Cloud KMS and HSM key stores do not accept imported keys. In the dashboard, this is Import Key.
As the import is a file upload (multipart/form-data), the request is shown with curl:
read -rs KEY_PASSWORD # the password of the file; the terminal does not show it
curl -X POST "https://demo-api.igrant.io/v4/config/ows/key-management/keys/import" \
-H "Authorization: ApiKey $API_KEY" \
-F "[email protected]" \
--form-string "password=$KEY_PASSWORD" \
-F "name=PID issuance 2026"
Example response (201):
{
"keyId": "3f2a91c47b8d4e6fa0c5d7e18b924f30",
"name": "PID issuance 2026",
"keyStore": { "id": "local-openbao", "type": "local", "name": "Local vault" },
"origin": "imported",
"algorithm": "ES256",
"status": "active",
"jwk": {
"kty": "EC",
"crv": "P-256",
"x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
"y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
"kid": "3f2a91c47b8d4e6fa0c5d7e18b924f30",
"alg": "ES256",
"x5c": ["MIICLzCCAdWgAwIBAgIUX2b7...", "MIIB9TCCAZugAwIBAgIUa1c4..."],
"x5c_expiry": "2027-10-22T09:30:00Z"
},
"hasCertificateChain": true,
"certificateSource": "imported",
"testCertificate": false,
"certificatePreset": null,
"qscd": false,
"trust": null,
"createdAt": "2026-10-22T09:30:00Z",
"updatedAt": "2026-10-22T09:30:00Z"
}
507. The response has no Retry-After, and retrying fails in the same way until there is room. For your own DPoD partition, remove unused key pairs or add capacity, then try again. If the local vault of your installation uses an HSM, contact the operator of your installation. Any request that creates a key in such a key store can return this response, including test certificates, test CAs and the OpenID Conformance extension.Step 5: Get a Certificate for a Key
For production:
- Generate a CSR with Generate CSR, using the certificate preset for the purpose of the key. Each example shows every field of the request, filled in with the value that the wallet uses if you leave the field out: the fixed values of the preset and the details of your organisation (here Example AB). You can change any value, or leave a field out to use the wallet's value. A value that differs from a fixed value of the preset gives the warning
preset-override.
Request
Response
Example- Send the CSR to your CA or QTSP and ask for the certificate profile of that preset. The CA decides the final content of the certificate.
- Upload the chain with [Upload Certificate Chain](/docs/openid4vc-api/config-digital-wallet-open-id-upload-certificate-chain/): a PEM file with the leaf certificate first, then any intermediate certificates, then the root. This is also a file upload (`multipart/form-data`):
curl -X POST "https://demo-api.igrant.io/v4/config/ows/key-management/keys/$KEY_ID/certificate-chain" \
-H "Authorization: ApiKey $API_KEY" \
-F "[email protected]"
Example response (200):
{
"key_id": "3f2a91c47b8d4e6fa0c5d7e18b924f30",
"certificates_count": 2,
"x5t": "Pc9qa0x1tWfGqFOAPfUzjgKCOyk",
"x5t_s256": "3T1jzz8BK8b6vrTVo2C5sm8Ehb0cDcnfjVEHg9ZJ7ZM",
"csrId": "5e1c2f7a-8b3d-4c6e-9f0a-1b2c3d4e5f60",
"preset": "eaa-provider",
"warnings": [],
"affectedCredentialConfigurations": []
}
The wallet compares the certificate with the preset of the key's latest CSR and warns you about any differences (profile-mismatch), but it does not reject the upload. A new upload replaces the existing chain.
In the dashboard, click View Key on the key, then Generate CSR in Key Details. Select the Certificate Preset and click Generate. When the certificate arrives, click Upload Certificate Chain.
The built-in test CA (development and testing)
For development and testing, the built-in test CA issues a certificate and stores the chain on the key in a single call: Create Test Certificate. The body is the same as for a CSR, with an optional validityDays (the examples show the installation default of 365 days). In the dashboard, switch on Use the built-in test CA in Generate CSR.
Request
Response
Example- Each organisation has three test root CAs, one for each trust domain:
mdoc-iacafor mdoc,accessfor access certificates (WRPAC) andrequest-signer-san-dns, andproviderfor all other presets. The first test certificate in a domain creates its root, and Read Test CA lists the roots. - For mdoc, the Document Signer, the IACA and the mdoc
issuing_countrymust share a country. To choose that country, create the root first with Create Test CA. - Verifiers and wallets on this platform trust a test certificate only if they add its root as a trust anchor with the role of the certificate (Add trust source), or if one of their list trust sources contains the root.
- A new test certificate replaces and revokes the previous one. If a key has a chain from another CA, delete that chain first.
- The dashboard marks these keys with the Test certificate badge. Your installation can switch the test CA off, in which case the test CA requests return
403.
Step 6: Register the Certificate in a Trust List
Wallets trust your organisation when a trust list contains your certificate or its CA. To join the NXD trust list, follow Register as a Wallet-Relying Party and send the request to [email protected]. Trust in the Wallet Ecosystem explains how trust lists work.
- Issuers of PID, EAA, QEAA or PuB-EAA credentials belong in the list for that category. Verifiers belong in the Wallet-Relying Party Access Certificate (WRPAC) list.
- The EU lists of trusted entities (ETSI TS 119 602) and the EU trusted lists hold the CA certificate, not your leaf certificate. For access certificates (WRPAC), that is the Access CA of the trust service provider that issued them. The NXD trust list registers the WRPAC of a relying party directly.
- Signatures carry the leaf and intermediate certificates but not the root (OpenID4VC HAIP), so wallets and verifiers build the path to a CA on their own list themselves.
- In tests, the roots of the built-in test CA take the place of these CAs.
Step 7: Manage Your Keys
Find keys. List Keys returns each key with its key store, public key, certificate details and usage count, and you can filter the list, for example to the keys that have a certificate. Read Key returns a single key.
Request
Response
ExampleSee where a key is used. Read Key Usage lists the credential definitions, presentation definitions and status lists that sign with the key, and canDelete tells you whether the key can be deleted.
Request
Response
ExampleDelete a key. Delete Key needs the body {"confirm": "DELETE"} and returns 204 with no body. The wallet key (the key that the platform creates for your organisation automatically) and keys that are in use cannot be deleted. Deleting a key retires it: it no longer signs anything and disappears from the key list, but its record keeps the certificate chain as evidence of what it signed. The wallet destroys the private key in the key store, including a key that you referenced from your own key store, unless another key in the wallet still uses the same private key. A key at a QTSP stays with the QTSP; the wallet simply stops using it.
Request
Response
Example- Rename a key: Update Key. For a QTSP key, the same call changes the PIN.
- Remove a certificate chain: Delete Certificate Chain with
{"confirm": "DELETE"}. This is rejected while the key still signs withx509, so move those uses to another key first. - Renew a certificate: a key with an expired certificate stops signing with
x509.jwk.x5c_expiryshows when the certificate expires, so upload a new chain before then. Note that an mdoc is never valid beyond its Document Signer certificate.
In the dashboard, click View Keys on a key store, then View Key, Edit Key or Delete Key. Key Details shows the certificate chain, where the key is used, and Delete Certificate Chain. In the developer guides on this site, the key label next to each signing key field lets you pick one of your keys.
Credential Categories and Key Usage Types
Each credential configuration has a credential category (eaa, qeaa, pub-eaa, mdl or pid), and the category determines which certificate its signing key needs. The API compares the certificate with the category and shows the result in signingKeyCheck. This is for information only and does not block a save, but a wallet or verifier may reject a credential whose certificate does not fit, so request your certificate with the preset of the category.