POST/api/v1/register-key

Register a signing key

Registers the public part of the caller's signing key so they can take part in vault approvals, reading the Bitcoin network from the derivation path and replacing any key already active on that network.

AccessRequires a signed-in caller

A signing key is a member's personal approval credential. This call sends only its public part: the extended public key, the path it was derived at, and optional identifying details. Private keys never leave the member's own device, and nothing you send here can be used to reconstruct one. The key registers to the caller, so each member registers their own.

You do not choose the network in the request. It is read from derivation_path, where m/84'/0'/… is mainnet and m/84'/1'/… is testnet. A member keeps one active key per network, so registering again for the same network replaces the earlier key. The new key's id comes back in the message field of the response.

Re-registering replaces the active key

Registering a key for a network that already has one replaces the key that was active on it. A vault's signer set is fixed when the vault is created, so replacing a key does not change the signer set of any vault that already lists it.

Body parameters

key_typestringrequired

The kind of key being registered. Use hd_xpub.

xpubstringrequired

The account-level extended public key. This is the only part of the key the platform ever receives.

derivation_pathstringrequired

The account path the extended public key was derived at, for example m/84'/0'/0'. The Bitcoin network is read from it: m/84'/0'/… registers a mainnet key and m/84'/1'/… a testnet key.

master_fingerprintstringoptional

Fingerprint of the master key the account key descends from, in hex.

pubkey_hexstringoptional

The compressed public key in hex.

labelstringoptional

A display name for the key, shown wherever the key appears in the application.

bash

curl -X POST "$SQRL_API/api/v1/register-key" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "key_type": "hd_xpub",
        "xpub": "<account-zpub>",
        "derivation_path": "m/84'\''/0'\''/0'\''",
        "master_fingerprint": "7f3a1c4d",
        "pubkey_hex": "<compressed-pubkey-hex>",
        "label": "Treasury signing key"
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/register-key`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    key_type: "hd_xpub",
    xpub: "<account-zpub>",
    derivation_path: "m/84'/0'/0'",
    master_fingerprint: "7f3a1c4d",
    pubkey_hex: "<compressed-pubkey-hex>",
    label: "Treasury signing key",
  }),
});
const { message } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/register-key", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "key_type": "hd_xpub",
        "xpub": "<account-zpub>",
        "derivation_path": "m/84'/0'/0'",
        "master_fingerprint": "7f3a1c4d",
        "pubkey_hex": "<compressed-pubkey-hex>",
        "label": "Treasury signing key",
    }))
    .send()
    .await?;

Response200 OK

{
"message": "key_01HZX4M8QT"
}

#What happens next

The key is now available to whoever assembles a vault's approver set. It appears in GET /api/v1/list-keys for you, and in GET /api/v1/list-keys-workspace for members who hold PAYMENT_INIT in the workspace. Pass its id in key_ids when you create a vault on the same network.

Was this page helpful?