> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Governance Signing with the SDKs

> Add and remove signer group members, change a group's governance and collect a quorum of ES256 or passkey signatures with the TypeScript and Go SDKs

Some signer group changes need signatures from the group's [governance](https://docs.dakota.xyz/documentation/signing-guide.md#signer-group-governance): adding or removing members, and changing who governs the group. They need them when your team has [governance enforcement](https://docs.dakota.xyz/documentation/signing-guide.md#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](https://docs.dakota.xyz/documentation/signing-guide.md) explains the model behind them: who signs, how the quorum is counted, and what every intent contains.

***

> [!NOTE]
>
> **We plan to make [governance enforcement](https://docs.dakota.xyz/documentation/signing-guide.md#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`](https://docs.dakota.xyz/api-reference/errors#insufficient-endorsements) and retry `503` responses, such as [`check_unavailable`](https://docs.dakota.xyz/api-reference/errors#check-unavailable).

## Install

```bash TypeScript theme={null}
npm install @dakota-xyz/ts-sdk@^3.4.0
```

```bash Go theme={null}
go get github.com/dakota-xyz/go-sdk@latest
```

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.

> [!WARNING]
>
> 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](#collect-a-quorum-over-time) flow.

### Add and remove members

```typescript TypeScript theme={null}
import { DakotaClient, Environment, ES256Signer } from '@dakota-xyz/ts-sdk';

const client = new DakotaClient({
  apiKey: process.env.DAKOTA_API_KEY,
  environment: Environment.Sandbox,
});

// PEM, DER or a KeyObject. Or implement GovernanceSigner over your KMS.
const admin = ES256Signer.fromPrivateKey(process.env.ADMIN_KEY_PEM!);

// Add one member, signed by the group's current governance
let group = await client.signerGroups.addSignerSigned(groupId, newMemberPublicKey, [admin]);

// Remove one or more members, by public key
group = await client.signerGroups.removeSignersSigned(groupId, [oldMemberPublicKey], [admin]);
// group.version moves on by 1 with every change
```

```go Go theme={null}
import (
    "os"

    "github.com/dakota-xyz/go-sdk/client"
)

c, err := client.New(
    client.WithAPIKey(os.Getenv("DAKOTA_API_KEY")),
    client.WithEnvironment(client.EnvironmentSandbox),
)

// adminKey is a *client.P256Signer (client.P256SignerFromKey), or your HSM or KMS behind client.Signer
admin := client.ES256IntentSigner(adminKey)

// Add one member, signed by the group's current governance
group, err := c.AddSignerToGroupSigned(ctx, groupID, newMemberPublicKey, admin)

// Remove one or more members, by public key
group, err = c.RemoveSignersFromGroupSigned(ctx, groupID, []string{oldMemberPublicKey}, admin)
```

* 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](#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.

> [!WARNING]
>
> **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`.

```typescript TypeScript theme={null}
// Read the group, then pass every setting you want to keep
const current = await client.signerGroups.get(groupId);

const group = await client.signerGroups.updateGovernanceSigned(
  groupId,
  {
    governance_threshold: 2,                                         // the change
    governance_signer_group_id: current.governance_signer_group_id, // kept as it is
  },
  [admin, secondAdmin], // ES256Signers of the CURRENT governance, at its current quorum
);
```

```go Go theme={null}
// Read the group, then pass every setting you want to keep
current, err := client.CheckResponse(c.Raw().GetSignerGroupWithResponse(ctx, groupID, nil))
if err != nil {
    return err
}

two := int32(2)
group, err := c.UpdateSignerGroupGovernanceSigned(ctx, groupID,
    client.GovernanceSettings{
        GovernanceThreshold:     &two,                                    // the change
        GovernanceSignerGroupID: current.JSON200.GovernanceSignerGroupId, // kept as it is
        // AllowClearing: true is needed only to clear a setting on purpose
    },
    admin, secondAdmin, // IntentSigners of the CURRENT governance, at its current quorum
)
```

The new settings must leave a quorum someone can meet. The rules for both fields are in [Update Signer Group Governance](https://docs.dakota.xyz/documentation/signing-guide.md#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.

```typescript TypeScript theme={null}
// 1. Prepare: reads the version and fixes the idempotency key
const change = await client.signerGroups.prepareRemoveSigners(groupId, [memberPublicKey]);
await store.save(change.idempotencyKey, change); // plain JSON

// 2. Collect: each signer signs change.canonical, the exact bytes of the intent
const bytes = new TextEncoder().encode(change.canonical);
const sigAlice = alice.sign(bytes);          // an ES256Signer
const sigBob = await bobsSigner.sign(bytes); // any GovernanceSigner, or a passkey (below)

// 3. Submit, with the same key and version the signatures cover
const group = await client.signerGroups.submitSignedChange(change, [sigAlice, sigBob]);
```

```go Go theme={null}
// 1. Prepare: reads the version and fixes the idempotency key
intent, err := c.PrepareRemoveSignersFromGroup(ctx, groupID, []string{memberPublicKey})
saved, err := json.Marshal(intent) // store it while you collect signatures

// 2. Collect: each signer signs intent.Canonical, the exact bytes of the intent.
// intent.Sign checks Canonical against the intent's fields before signing.
sigs, err := intent.Sign(ctx, client.ES256IntentSigner(alice))
sigBob, err := client.EncodeWebAuthnAssertion(intent.Canonical, bobsAssertionJSON) // a passkey (below); bobsAssertionJSON is a []byte
sigAlice := sigs[0]

// 3. Submit, with the same key and version the signatures cover
group, err := c.SubmitGovernanceIntent(ctx, intent, []string{sigAlice, sigBob})
```

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.

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant S as Your server
    participant D as Dakota API
    B->>S: Approve "add member"
    S->>D: GET /signer-groups/{id} (prepare)
    D-->>S: group with version
    S-->>B: change.canonical
    B->>B: navigator.credentials.get(challenge = canonical bytes)
    B->>S: packed assertion
    S->>S: check the assertion is over this change
    S->>D: POST /signer-groups/{id}/signers + signatures
    D-->>S: updated group
```

**1. Prepare the change on your server**

```typescript theme={null}
// server
const change = await client.signerGroups.prepareAddSigner(groupId, newMemberPublicKey);
session.pendingChange = change;     // plain JSON: keep it server-side
return { canonical: change.canonical };
```

**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.

```typescript theme={null}
// browser
import { buildChallenge, packAssertion } from '@dakota-xyz/ts-sdk/governance';

const credential = await navigator.credentials.get({
  publicKey: {
    challenge: buildChallenge(canonical),
    rpId: 'app.example.com',       // your domain, as at registration
    userVerification: 'required',  // the person approves, not just the device
    allowCredentials: [{ type: 'public-key', id: approverCredentialId }],
  },
});

const signature = packAssertion(credential as PublicKeyCredential);
await fetch('/governance/approve', { method: 'POST', body: JSON.stringify({ signature }) });
```

**3. Check and submit on your server**

```typescript theme={null}
// server
import { assertionChallengeMatches } from '@dakota-xyz/ts-sdk';

const change = session.pendingChange;
if (!assertionChallengeMatches(signature, change)) {
  throw new Error('this passkey assertion was not made over this change');
}
const group = await client.signerGroups.submitSignedChange(change, [signature]);
```

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:

```go theme={null}
// server, after the browser returns credential.toJSON()
sig, err := client.EncodeWebAuthnAssertion(intent.Canonical, assertionJSON)
if err != nil {
    return err // not made over this intent, or not a valid assertion
}
group, err := c.SubmitGovernanceIntent(ctx, intent, []string{sig})
```

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](https://docs.dakota.xyz/documentation/webauthn-signing.md).

***

## 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](https://docs.dakota.xyz/documentation/authentication/api-key-scopes.md) 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](https://docs.dakota.xyz/documentation/signing-guide.md#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:

```typescript TypeScript theme={null}
import {
  createCryptoDestinationIntent,
  newIdempotencyKey,
  signGovernanceIntent,
} from '@dakota-xyz/ts-sdk';

const idempotencyKey = newIdempotencyKey(); // lowercase UUID
const intent = createCryptoDestinationIntent({
  recipientId,
  networkId: 'ethereum-sepolia',
  address,              // exactly as you send it
  signerGroupId,        // a group on a wallet of the recipient's customer
  idempotencyKey,
});
const signatures = await signGovernanceIntent(intent, [owner]); // its quorum of signers

const destination = await client.destinations.create(
  recipientId,
  {
    destination_type: 'crypto',
    name: 'Treasury',
    crypto_address: address,
    network_id: 'ethereum-sepolia', // needed on a signed request: the intent names it
    signer_group_id: signerGroupId,
    signatures,
  },
  { idempotencyKey }, // the key inside the signed intent
);
```

```go Go theme={null}
import (
    "github.com/dakota-xyz/go-sdk/client"
    "github.com/dakota-xyz/go-sdk/client/gen"
    "github.com/google/uuid"
)

key := uuid.New()
network := gen.NetworkId("ethereum-sepolia")
intent, err := client.CreateCryptoDestinationIntent(recipientID, string(network), address, signerGroupID, key.String())
sig, err := client.ES256IntentSigner(owner).SignIntent(ctx, intent)

var body gen.CreateDestinationJSONRequestBody
err = body.FromCryptoDestinationRequest(gen.CryptoDestinationRequest{
    DestinationType: gen.CryptoDestinationRequestDestinationTypeCrypto,
    Name:            "Treasury",
    CryptoAddress:   address,  // exactly as signed
    NetworkId:       &network, // needed on a signed request: the intent names it
    SignerGroupId:   &signerGroupID,
    Signatures:      &[]string{sig},
})
resp, err := client.CheckResponse(c.Raw().CreateDestinationWithResponse(ctx, recipientID,
    &gen.CreateDestinationParams{XIdempotencyKey: key}, body))
// resp.JSON201.Id is the new destination's id
```

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](https://docs.dakota.xyz/documentation/signing-guide.md#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](https://docs.dakota.xyz/documentation/signing-guide.md#errors) section.

| `reason` | TypeScript (an `APIError`) | Go (`errors.Is(err, …)`) |
| - | - | - |
| `endorsement_required` | `EndorsementRequiredError` | `client.ErrEndorsementRequired` |
| `insufficient_endorsements` | `InsufficientEndorsementsError` (with `have` and `need` when Dakota reports them) | `client.ErrInsufficientEndorsements` |
| `stale_signer_group_version` | `StaleSignerGroupVersionError` | `client.ErrStaleSignerGroupVersion` |
| `below_threshold` | `BelowThresholdError` | `client.ErrBelowThreshold` |
| `invalid_governing_group` | `InvalidGoverningGroupError` | no named sentinel: `&client.ProblemCodeError{Status: 409, Code: "invalid_governing_group"}` |

```typescript TypeScript theme={null}
import { StaleSignerGroupVersionError, InsufficientEndorsementsError } from '@dakota-xyz/ts-sdk';

try {
  await client.signerGroups.submitSignedChange(change, signatures);
} catch (err) {
  if (err instanceof StaleSignerGroupVersionError) {
    // the group changed after signing: prepare and sign again
  } else if (err instanceof InsufficientEndorsementsError) {
    // too few governing signatures (err.have of err.need):
    // prepare the change again and collect the whole quorum over it
  } else {
    throw err;
  }
}
```

```go Go theme={null}
_, err := c.SubmitGovernanceIntent(ctx, intent, signatures)
switch {
case errors.Is(err, client.ErrStaleSignerGroupVersion):
    // the group changed after signing: prepare and sign again
case errors.Is(err, client.ErrInsufficientEndorsements):
    // too few governing signatures: prepare again and collect the whole quorum over it
case err != nil:
    return err
}
```

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](https://docs.dakota.xyz/documentation/signing-guide.md#errors) and [WebAuthn troubleshooting](https://docs.dakota.xyz/documentation/webauthn-signing.md#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:

> [card] [TypeScript examples](https://github.com/dakota-xyz/dakota-ts-sdk/tree/main/examples)
>
> `governance-es256.ts` (ES256 keys, including a quorum change to 2) and `governance-passkey.ts` (a passkey with an ES256 key)

> [card] [Go example](https://github.com/dakota-xyz/go-sdk/tree/main/cmd/signer-group-governance)
>
> `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.