Manage Wallets and Keys

A wallet is the container the SVX Wallet manages on behalf of a holder — a collection of cryptographic keys, DIDs and credentials. This guide covers the lifecycle of a wallet and of the keys it holds.

All requests require a Bearer access token — see Using the Wallet API.

Wallets

Create a wallet

A wallet is identified by an external_reference you choose — typically a stable identifier for the user or integration the wallet belongs to.

Endpoint

POST /wallets

Request

{
  "external_reference": "wallet-240201"
}

Response

The new wallet is returned with its system-generated id and its (initially empty) keys and dids.

{
  "wallet": {
    "id": "e9f0451b-27a0-4db1-bc7a-ae6dd176a456",
    "external_reference": "wallet-240201",
    "keys": [],
    "dids": []
  }
}

Note Find-or-create: this endpoint is idempotent on external_reference. If no wallet exists for the reference, a new one is created and returned with 201 Created. If a wallet already exists for that reference, the existing wallet is returned with 200 OK rather than creating a duplicate.

View a wallet

Retrieve a wallet by its id, including the keys and DIDs it currently holds.

Endpoint

GET /wallets/{walletId}

Response

{
  "wallet": {
    "id": "e9f0451b-27a0-4db1-bc7a-ae6dd176a456",
    "external_reference": "wallet-240201",
    "keys": [
      {
        "kid": "lA5y6IC-aLCpHtf-NytvSbYGZWqAfbrgAoGn3F3l0NI",
        "alg": "ES256",
        "kty": "EC",
        "crv": "P-256",
        "x": "LJJiy0X4NtQAI67uLsr883v0aFEk81LoxJ7xoJwfwyk",
        "y": "mZXpWtIIj3137AjvIeFuAd5g5bE6crBizyloOBFu9ek"
      }
    ],
    "dids": [
      {
        "id": "did:key:zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169",
        "keys": [{ "kid": "did:key:zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169#zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169" }]
      }
    ]
  }
}

Only the public part of each key is ever returned; private key material never leaves the service.

Delete a wallet

Endpoint

DELETE /wallets/{walletId}

A successful deletion returns an empty 204 No Content response.

Note Deleting a wallet permanently removes it together with all of its keys and DIDs. This cannot be undone. Credentials held in the wallet are no longer usable once the keys they are bound to are gone.

Manage keys

Each key in a wallet is a key pair generated and held by the service. Keys are used to control DIDs, to bind credentials to the holder, and to sign verifiable presentations. A key is identified by its kid.

Create a key

Generates a new key pair in the wallet.

Endpoint

POST /wallets/{walletId}/keys

Request

{
  "key": {
    "kty": "EC",
    "crv": "P-256"
  }
}

Supported key types:

kty	crv
EC	P-256
OKP	Ed25519

Response

The public key is returned, including the generated kid and the JWA alg it maps to (ES256 for EC / P-256).

{
  "key": {
    "kid": "lA5y6IC-aLCpHtf-NytvSbYGZWqAfbrgAoGn3F3l0NI",
    "alg": "ES256",
    "kty": "EC",
    "crv": "P-256",
    "x": "LJJiy0X4NtQAI67uLsr883v0aFEk81LoxJ7xoJwfwyk",
    "y": "mZXpWtIIj3137AjvIeFuAd5g5bE6crBizyloOBFu9ek"
  }
}

View a key

Endpoint

GET /wallets/{walletId}/keys/{kid}

Returns the public key for the given kid, in the same shape as the create response.

Delete a key

Endpoint

DELETE /wallets/{walletId}/keys/{kid}

A successful deletion returns an empty 204 No Content response. Credentials or DIDs bound to the key can no longer be used once it is deleted.

Import a key

For advanced use, an existing key pair can be imported into a wallet by supplying the full JWK (including its private members) rather than generating a new one.

Endpoint

POST /wallets/{walletId}/keys/import

Request

{
  "key": {
    "kty": "EC",
    "crv": "P-256",
    "x": "LJJiy0X4NtQAI67uLsr883v0aFEk81LoxJ7xoJwfwyk",
    "y": "mZXpWtIIj3137AjvIeFuAd5g5bE6crBizyloOBFu9ek",
    "d": "…"
  }
}

The imported key is stored like any other and the public key is returned.

Sign data with a key

For advanced use, a wallet key can sign an arbitrary payload directly. Most callers do not need this — credential binding and presentation signing happen automatically as part of the relevant flows.

Endpoint

POST /wallets/{walletId}/keys/{kid}/sign

Request

{
  "data": "<base64url-encoded bytes to sign>"
}

Response

{
  "signature": "<base64url-encoded signature>"
}

Related

• DIDs — create and use DIDs derived from a wallet's keys.

• Add Credentials to a Wallet — receive or import credentials into a wallet.

• Credentials — work with credentials once stored.