Local Keys

Local keys are generated and stored by the wallet as JWKs in the configured database if persistence is enabled. This page covers generating a key, importing existing key material, and listing or deleting keys.

See Key Management for how the wallet chooses a default key.

Local Development: the API is available at http://localhost:7006 by default, whether Wallet API v2 runs standalone or via the Docker Compose quick start.

Generate a Key

Create a new key in the wallet's key store.

CURL

Endpoint: POST /wallet/{walletId}/keys/generate | API Reference

Example Request
curl -X POST http://localhost:7006/wallet/{walletId}/keys/generate \
  -H 'Content-Type: application/json' \
  -d '{ "backend": "jwk", "keyType": "secp256r1" }'

Path Parameters

  • walletId: String (required) - The wallet to add the key to. See Managing Wallets.

Body Parameters

  • backend: String (required) - The key backend.
  • keyType: String (optional) - One of Ed25519, secp256r1, secp256k1, secp384r1, secp521r1, RSA, RSA3072, RSA4096. Defaults to secp256r1.

    Prefer secp256r1 (ES256) unless you have a specific reason to use another type. The Issuer2 and Verifier2 quick-start examples (and the wallet-attestation flow, if enabled) advertise ES256 only — an Ed25519 (EdDSA) key will fail with invalid_proof when receiving, or be rejected outright by attestation providers that don't support OKP keys.

Example Response
{
  "keyId": "UneoCeKrx7t0SBINBZQOaSCCzvhgpK8tRS3NEG4pCfU",
  "keyType": "secp256r1"
}

Response Fields

  • keyId: String - The new key's ID. Use it as keyId when receiving, presenting, or creating a DID.
  • keyType: String - The key type.

Import a Key

Import existing key material as a JWK.

CURL

Endpoint: POST /wallet/{walletId}/keys/import | API Reference

Example Request
curl -X POST http://localhost:7006/wallet/{walletId}/keys/import \
  -H 'Content-Type: application/json' \
  -d '{
    "key": {
      "type": "jwk",
      "jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "d": "..." }
    }
  }'

Path Parameters

  • walletId: String (required) - The wallet to import the key into.

Body Parameters

  • key: Object (required) - The serialized key. type is jwk, and jwk carries the JWK (include the private d component for a signing key).
Example Response
{
  "keyId": "UneoCeKrx7t0SBINBZQOaSCCzvhgpK8tRS3NEG4pCfU",
  "keyType": "secp256r1"
}

List Keys

List the metadata of all keys across the wallet's key stores.

CURL

Endpoint: GET /wallet/{walletId}/keys | API Reference

Example Request
curl http://localhost:7006/wallet/{walletId}/keys

Path Parameters

  • walletId: String (required) - The wallet whose keys you want to list.
Example Response
[
  { "keyId": "UneoCeKrx7t0SBINBZQOaSCCzvhgpK8tRS3NEG4pCfU", "keyType": "secp256r1" }
]

Get a Key

Fetch a single key's metadata.

CURL

Endpoint: GET /wallet/{walletId}/keys/{keyId} | API Reference

Example Request
curl http://localhost:7006/wallet/{walletId}/keys/{keyId}

Path Parameters

  • walletId: String (required) - The wallet holding the key.
  • keyId: String (required) - The key to fetch. Obtain it from list keys or the generate/import response.
Example Response
{ "keyId": "UneoCeKrx7t0SBINBZQOaSCCzvhgpK8tRS3NEG4pCfU", "keyType": "secp256r1" }

Delete a Key

CURL

Endpoint: DELETE /wallet/{walletId}/keys/{keyId} | API Reference

Example Request
curl -X DELETE http://localhost:7006/wallet/{walletId}/keys/{keyId}

Path Parameters

  • walletId: String (required) - The wallet holding the key.
  • keyId: String (required) - The key to delete.
Example Response

204 No Content on success, or 404 Not Found if the key doesn't exist.

Set the Default Key

Set the key the wallet uses when a receive, present, or DID creation request omits keyId.

CURL

Endpoint: PUT /wallet/{walletId}/keys/{keyId}/set-default | API Reference

Example Request
curl -X PUT http://localhost:7006/wallet/{walletId}/keys/{keyId}/set-default

Path Parameters

  • walletId: String (required) - The wallet holding the key.
  • keyId: String (required) - The key to make the wallet's default.
Example Response

204 No Content on success, or 404 Not Found if the key doesn't exist in the wallet.

Next Steps

Last updated on August 18, 2026
OverviewKey Management