A signer doesn’t have to be a person with a passkey. If Conduit has enabled a programmatic signing mode for your customer, your backend can hold a signing key and approve payouts server-to-server, with no browser and no human. See Programmatic payout signing.
When to use which custody model
By default, customers provision non-custodial wallets via theclaim-non-custodial endpoint, which always creates a roster of at least two admins. You choose the M-of-N signing threshold — as low as 1 (a single stamp clears each payout) or higher for multi-party approval. The custodial column below applies only to orgs Conduit has configured for custodial wallets; for those, POST /v2/customers/:id/wallets provisions the account directly with no claim.
Every non-custodial wallet is a roster of at least two admins; the signing threshold M is what you choose. Threshold 1 clears on a single stamp, higher thresholds need M stamps. The custodial model has no customer signer at all. The passkey columns above describe the passkey-required signing mode; in a programmatic signing mode, signer seats (and, in the unattended variant, admin seats) can be held by machine API keys instead — see Programmatic payout signing.
Concepts
Roster. The ordered list of named signers attached to a customer’s non-custodial setup. Each signer has an email, a role (admin or signer), and a credential: passkey members enroll passkeys — plain signers one, admins two on two separate devices (see Backup passkeys) — while machine (api_key) members carry a registered P-256 public key and enroll nothing. The email identifies and dedups the signer — Conduit never contacts the signer directly; distributing each signer’s enrollment link is your responsibility (see Lifecycle endpoints below). Roster size and threshold are decoupled: a 5-member roster can require 2 stamps; a 2-member roster can require 2.
The customer’s signing mode constrains the roster, both at claim time and on later adds: api_key members are rejected in the passkey-required mode, and an api_key member with role: "admin" is rejected outside the unattended mode — both with 422 SIGNING_MODE_ROSTER_INVALID. In either programmatic mode the machine signers alone must be able to reach signingThreshold; a roster where they can’t (including an all-passkey roster) is rejected with 422 PROGRAMMATIC_QUORUM_UNREACHABLE.
Threshold. The integer M in M-of-N. Every payout collects stamps until M are recorded, then auto-broadcasts. The threshold is set at claim-non-custodial time and can be adjusted later via the signing-quorum endpoints. See Signing thresholds for the constraints.
Admin vs signer. Both roles stamp payouts; only admins can change the roster (add, remove, promote, demote other members). The minimum-admin floor (2 admins) is enforced on every roster mutation so you can never lock yourself out.
Root quorum. The governance layer that protects the customer’s signing setup itself — the roster of allowed signers, the threshold, the underlying keys. It is a fixed set: two Conduit seats plus exactly two customer admin seats, and it always requires all but one of its members to approve a governance change. Because the two customer seats can never reach that bar on their own, no roster or threshold change goes through without a Conduit approval — that is the governance veto. The customer chooses which two of their admins hold the root seats when they claim the wallet.
Non-root admins. A customer can have more than two admins. Every admin can co-approve governance changes, but only the two who hold root seats are counted toward the root quorum. Admins beyond those two are non-root admins: full admins on the roster, not members of the root quorum. Promoting a signer or non-root admin into the root quorum is a seat swap, never an addition — the root quorum stays at two customer seats.
Ceremony. A short-lived background flow that updates the root quorum (on promote/demote) or rolls the roster (on add/remove). Ceremonies are sequential per customer; a second one queues if one is already in flight. You see this surface as: a promote/demote operation returns 202 Accepted and the change shows up after the ceremony completes.
Roster changes and the payout threshold are separate. Adding or removing a signer takes a single admin approval, no matter what signing threshold you set. Your signingThreshold governs only how many stamps a payout needs; it does not change how many admins must approve a roster change. So a one-admin approval on an add or remove is expected even on a wallet that requires several stamps per payout — the two settings are independent.
Ghost-vote scrubbing. If a signer is removed while a payout is sitting at the quorum gate, that signer’s already-cast stamps are scrubbed from every in-flight payout for the customer. Affected payouts re-fire transaction.signature_collected with the new count; payouts that can no longer reach quorum on the new roster terminate with failureCode: "roster_changed" so clients can re-submit against the current roster.
Backup passkeys
A plain signer enrolls with one passkey; an admin enrolls two, on two separate devices, so losing one device never unseats an admin. Any active signer can add another passkey after enrollment from the Conduit-hosted signer profile athttps://app.conduit.financial/signer-profile — one stable page for every signer, with no per-signer token: the signer opens it, signs in with an existing passkey, and registers a new device. Unlike the enrollment link (one tokenized URL per invited signer), this is a single fixed URL you can publish to your whole roster. The add takes a single admin co-approval before the new passkey is usable: the request parks pending approval and returns an adminVerificationUrl (in a 409 parked-pending-approval response body) for one of your admins to approve. Because the signer is already active, approving fires wallet_signer.enrollment_approved — not wallet_signer.enrolled, which only fires on a signer’s first activation — and no wallet_ceremony.* webhook fires for this self-service path. Distributing both the signer-profile URL and the admin-approval link is your responsibility — Conduit never contacts signers directly.
Because a root-quorum admin must hold two passkeys, a plain signer has to add a second passkey before it can be promoted into the root quorum.
Recovery
Recovery replaces a signer’s or admin’s passkey when a device is lost — without re-onboarding the customer or re-claiming the wallet. It is admin-driven: a customer admin initiates it from the Conduit dashboard (not through the public API), and a locked-out signer can separately signal intent from their signer profile. Conduit co-approves every recovery — the same governance veto that protects roster changes — and high-risk patterns (a second recovery within a short window, or overlapping open cases) are auto-refused. A recovery may include a cooling-off delay before it completes. From an integration’s point of view recovery surfaces as a ceremony on your webhook stream, with no roster-membership change (sowallet_signer.added / wallet_signer.removed do not fire):
wallet_ceremony.awaiting_admin_approvalwithtype: "recovery"— a recovery is open and waiting on an admin.wallet_ceremony.completed— the replacement credential is in place and the signer is usable again with the same seat.wallet_ceremony.failed— the recovery was declined, expired, or auto-refused by a risk check.
wallet.threshold_changed also fires.
Promoting into the root quorum is a seat swap
The root quorum holds a fixed number of customer seats (two). Once both are filled, you cannot grow it — promoting a signer into the root quorum means unseating an existing root admin in the same ceremony. This is the only way to change who holds a root seat; there is no “add a third root seat” path. Worked example. A customer claims with two admins, Ada and Grace, who take the two root seats, plus a signer, Ken. Later they want Ken in the root quorum. Because both root seats are filled, a bare promote is rejected with409 ROOT_AT_CAPACITY_SWAP_REQUIRED — there is no free seat to grant. The only way in is a seat swap:
- Put Ken in the root quorum (seat swap). Promote Ken and name the current root admin to unseat in the same call:
demoteSignerId= Grace’s signer id. One ceremony seats Ken and unseats Grace. The root quorum still holds two customer seats (Ada and Ken); Grace loses her admin role and reverts to a signer. The threshold is unchanged.
demoteSignerId is optional on the promote endpoint but required whenever the root quorum is already at its seat capacity. It must name a current root-quorum admin, and the swap must leave the roster with at least two admins. Because the root stays the same size, the governance veto never weakens: two customer seats, and a Conduit approval is always needed on top.
Lifecycle endpoints
For the quorum-threshold endpoints (per-customer + per-wallet overrides) see Signing thresholds.