Skip to main content
Some signer group changes need signatures from the group’s governance: adding or removing members, and changing who governs the group. They need them when your team has governance enforcement on, when the group has governance settings of its own, or when the group governs another group. Each signature covers a canonical intent that names the group’s current version and the request’s X-Idempotency-Key. Built by hand, a wrong key name or a stale version gives a signature that does not verify, and an uppercase idempotency key is refused. The TypeScript and Go SDKs build those intents byte for byte as Dakota verifies them, sign them with your ES256 keys or your users’ passkeys, and send the request. This page shows how to use them. The Signing guide explains the model behind them: who signs, how the quorum is counted, and what every intent contains.
We plan to make governance enforcement the default for all clients. Today it is off unless Dakota turns it on for your team, so build and test your integration as if it is on. In practice: collect signatures from signer group members for signer group, policy and wallet changes; manage API keys and users from a signed-in session, not with an API key; give your servers Operate keys that pass along those signed changes; and handle insufficient_endorsements and retry 503 responses, such as check_unavailable.

Install

The governance helpers are in @dakota-xyz/ts-sdk 3.4.0 and later. In Go, they are in github.com/dakota-xyz/go-sdk from commit 575a17e (18 November 2026) on. The TypeScript SDK has a second entry point, @dakota-xyz/ts-sdk/governance. It has no Node.js dependencies, so it bundles for browsers and React Native, where passkeys sign. Everything in it is also exported from the main entry point.

How the helpers work

Each one-call helper does the whole flow:
  1. Reads the signer group to get its current version.
  2. Generates a lowercase UUID idempotency key.
  3. Builds the canonical intent from the group, the change and the key.
  4. Asks each signer you pass to sign it, one after another.
  5. Sends the request with the signatures, the same version, and the same key as X-Idempotency-Key.
Pass as many signers as the group’s effective_governance_threshold: that many distinct members of its governing group must sign. The Go helpers refuse fewer signers before anyone is asked to sign. The TypeScript helpers send what you pass, and Dakota refuses a short quorum with insufficient_endorsements. A signer is anything that signs bytes: an ES256 key you hold (in memory, or behind your HSM or KMS), or a passkey. ES256 and passkey signatures can be combined toward one quorum.
Keep the governing keys and passkeys away from the service that holds your API key. Governance exists so that an API key alone cannot change who controls a wallet. If the same server holds both, whoever has that server can make any change.

Sign with an ES256 key (server)

This example uses an ES256 private key for an admin or a service that approves changes. For brevity it loads the API key and the governing key in one process. In production, keep them apart as the warning above says: for example, sign in an approval service or behind your KMS, and send the request from the service that holds the API key, with the prepare, collect, submit flow.

Add and remove members

  • The new member’s key must already be registered with POST /signers. A key cannot approve its own addition: the group’s governance as it was before the change signs it.
  • Removals name members by public key, as the group lists them. A removal that would leave the group below a threshold it must keep is refused (see Errors).

Update a group’s governance

A governance update sets the group’s governance_threshold (its quorum) and governance_signer_group_id (the group whose members govern it). The group’s current governance signs it.
An update replaces the group’s whole governance. A setting you leave out is cleared: no governance_threshold means the default quorum, and no governance_signer_group_id means the group governs itself. In TypeScript, updateGovernanceSigned({ governance_threshold: 2 }) on a group that has a governing group removes that governing group, without any warning. Read the group first and pass every setting you want to keep. To keep the quorum, pass the group’s governance_threshold as it is (null when it uses the default), not its effective_governance_threshold, which would pin today’s default as a fixed quorum. The Go SDK refuses to clear a setting the group has now unless you set AllowClearing: true.
The new settings must leave a quorum someone can meet. The rules for both fields are in Update Signer Group Governance.

Collect a quorum over time

When a group’s quorum is 2 or more, the signatures often come from different people at different times. Split the flow in three: prepare the change, collect the signatures, then submit it. The prepared change is plain JSON, so you can store it (in your database or a session) while you wait.
The prepare step exists for every change: prepareAddSigner, prepareRemoveSigners and prepareGovernanceUpdate in TypeScript, and PrepareAddSignerToGroup, PrepareRemoveSignersFromGroup and PrepareUpdateSignerGroupGovernance in Go.
  • Show each signer what they approve. canonical (Canonical in Go) is the exact JSON they sign.
  • Submit refuses a change whose stored fields no longer match its canonical intent, without sending anything. The Go SDK also refuses fewer signatures than the group’s quorum before sending.
  • Submit once, when you hold the whole quorum. If any change lands on the group in the meantime, its version moves on and the signatures no longer apply: prepare the change again and collect new signatures.

Sign with a passkey (browser)

A passkey lives in your user’s browser or device, and your API key stays on your server. So the change is prepared on the server, signed in the browser, and sent from the server.
1

Prepare the change on your server

2

Sign in the browser

Import from the browser-safe entry point. buildChallenge turns the canonical intent into the WebAuthn challenge: the raw canonical bytes, not their hash.
3

Check and submit on your server

For a quorum of 2 or more, collect one assertion per approving member, from their own passkeys, and submit them together. ES256 signatures over the same change.canonical can be part of the same array. With a Go server, prepare with PrepareAddSignerToGroup and send the canonical JSON to the browser as text, string(intent.Canonical). Canonical is a []byte, so putting it straight into a JSON response sends base64, and the passkey would sign that base64 instead of the intent. The browser signs the text as above and returns the assertion JSON (credential.toJSON()) instead of the packed string. The server packages it, checking that its challenge is this intent:
When the passkey ceremony can run from the same process, both SDKs also wrap it as a signer for the one-call helpers: webauthnSigner(getAssertion) in TypeScript and client.WebAuthnSigner(assert) in Go. The SDK passes your function the challenge, and your function returns the assertion. The passkey must be registered as a WEBAUTHN signer first. The assertion format and the checks Dakota runs on it are in WebAuthn (passkey) signing.

Retries and idempotency

The idempotency key is part of what is signed, so a signature only ever works with the key it was made over. Sending a successful change again with the same key within 24 hours returns the same response and changes nothing. A refusal from the policy engine is kept under the key for the same 24 hours: insufficient_endorsements, stale_signer_group_version and the passkey refusals (such as webauthn_wrong_type and webauthn_user_not_present). Other refusals, such as endorsement_required or a malformed X-Idempotency-Key, are not kept: fix the request and send it again.
  • A request that got no response (a timeout, a dropped connection) is safe to repeat. Resubmit the same prepared change with the same signatures. Don’t call a one-call helper again: each call generates a new key and asks every signer again.
  • A governance refusal is final for that change. After insufficient_endorsements, stale_signer_group_version or a passkey refusal, the same key returns the same refusal, and the same key with other signatures is refused as a different request. Prepare the change again, which gives it a new key, and collect every signature again over the new intent.
  • Stale versions in TypeScript. addSignerSigned and removeSignersSigned take { staleRetries: n } (0 to 5, default 0): after a stale version they read the group again, sign under a new key and resend. Each retry asks every signer again, so a passkey prompts again. updateGovernanceSigned refuses it, because re-signing a whole-governance change after someone else’s change would undo theirs. The Go SDK never re-signs on its own.

Signed crypto destinations (optional)

Adding a crypto destination does not need signatures. A Full access API key adds destinations unsigned, whether governance enforcement is on or off. The signed form is an option for teams with governance enforcement on. It lets an Operate API key add an address that the owners approved: the signatures of a signer group’s governance authorize the destination, and the Operate key only delivers it. Use it when the service that adds destinations should not hold a Full access key. See API key scopes for what each key can do. The signer group must be attached to one of the recipient’s customer’s wallets. A customer with no wallet has no group that can approve, so an Operate key’s request is refused with 403 insufficient_endorsements. Add that destination with a Full access key or from the dashboard instead, or create the customer’s wallet first with one of your existing signer groups in signer_groups (an Operate key can) and have that group sign. See Create Crypto Destination. Both SDKs build the create_crypto_destination intent. There is no one-call helper, so you generate the key, sign, and send it with the same key:
Each signed approval creates one destination: use a new idempotency key, and new signatures over it, for every address. The fields of the intent are in Create Crypto Destination.

Errors

The SDKs turn governance refusals into typed errors. The reason codes and what to do about each are in the Signing guide’s Errors section.
A passkey assertion the platform refuses (for example one from a registration ceremony, or one without the user-present flag) comes back as a 400 validation error with a reason of its own. The SDKs surface it as a plain APIError; see Errors and WebAuthn troubleshooting. The Go SDK refuses an assertion without the user-present flag before sending it.

Runnable examples

Each SDK has a sandbox walk-through that creates its own signers and signer groups, then runs signed adds and removals and shows the typed refusals:

TypeScript examples

governance-es256.ts (ES256 keys, including a quorum change to 2) and governance-passkey.ts (a passkey with an ES256 key)

Go example

cmd/signer-group-governance: a passkey and ES256 keys, an unsigned add refused, a stale version refused
Run them with the API key of a sandbox client.