Wallet Signers
Promote a signer to admin (root seat swap)
Promotes the signer into the root quorum via a ceremony. Under the fixed-seats model the root quorum holds a fixed number of customer admin seats, so when it is at capacity the request must name the current root admin to unseat (demoteSignerId): the swap seats the new admin and unseats the named one in one UPDATE_ROOT_QUORUM, keeping root size and threshold constant. Returns the ceremony id; completion is tracked via the wallet_signer.promoted / wallet_signer.demoted webhooks.
POST
/
customers
/
{customerId}
/
wallet-signers
/
{signerId}
/
promote
Promote a signer to admin (root seat swap)
curl --request POST \
--url https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '{}'import requests
url = "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote"
payload = {}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({})
};
fetch('https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_body{
"ceremonyId": "<string>"
}{
"type": "INVALID_OID_FORMAT",
"title": "Invalid Object ID Format",
"status": 400,
"detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
"resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
"docs": "https://conduit-v2.mintlify.app/errors#invalid-oid-format",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "API_KEY_MISSING",
"title": "API Key Missing",
"status": 401,
"detail": "The request did not include an API key. All API requests must be authenticated.",
"resolution": "Include your API key in the 'x-api-key' header with every request.",
"docs": "https://conduit-v2.mintlify.app/errors#api-key-missing",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "API_KEY_READ_ONLY",
"title": "API Key Is Read-Only",
"status": 403,
"detail": "This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only.",
"resolution": "Use a read-write API key for this request, or have an organization admin mint one from the dashboard.",
"docs": "https://conduit-v2.mintlify.app/errors#api-key-read-only",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "SIGNER_NOT_FOUND",
"title": "Signer Not Found",
"status": 404,
"detail": "No signer exists with the specified ID for this wallet.",
"resolution": "Verify the signer ID is correct and that it belongs to the specified wallet.",
"docs": "https://conduit-v2.mintlify.app/errors#signer-not-found",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "IDEMPOTENCY_KEY_CONFLICT",
"title": "Idempotency Key Conflict",
"status": 409,
"detail": "The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original.",
"resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
"docs": "https://conduit-v2.mintlify.app/errors#idempotency-key-conflict",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "UNSUPPORTED_MEDIA_TYPE",
"title": "Unsupported Media Type",
"status": 415,
"detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
"resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
"docs": "https://conduit-v2.mintlify.app/errors#unsupported-media-type",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "SIGNER_PASSKEY_COUNT_TOO_LOW",
"title": "Signer Passkey Count Too Low",
"status": 422,
"detail": "Promotion to admin requires a passkey-credential signer to have at least 2 registered passkeys so they cannot lose admin access by losing a single device. Machine (api_key) admins do not need passkeys and are exempt (allowed only in the fully-automated signing mode).",
"resolution": "Have the passkey signer register a second passkey from a different device, then retry the promotion.",
"docs": "https://conduit-v2.mintlify.app/errors#signer-passkey-count-too-low",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "RATE_LIMITED",
"title": "Rate Limited",
"status": 429,
"detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses.",
"resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
"docs": "https://conduit-v2.mintlify.app/errors#rate-limited",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z",
"retryAfterSeconds": 3
}{
"type": "INTERNAL_ERROR",
"title": "Internal Error",
"status": 500,
"detail": "An unexpected error occurred while processing your request.",
"resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
"docs": "https://conduit-v2.mintlify.app/errors#internal-error",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}Authorizations
Headers
Caller-generated unique key that lets the server safely replay this request. The original response is returned for 30 days on any retry with the same key from the same organization. Required on every state-changing money-moving or resource-creating POST.
Required string length:
1 - 128Pattern:
^[A-Za-z0-9_.:-]{1,128}$Example:
"01J7B3K2X9M8N5P6Q7R8S9T0V1"
Path Parameters
Example:
"cus_1A2b3C4d5E6f7G8h9I0jKl"
Example:
"wsg_1A2b3C4d5E6f7G8h9I0jKl"
Body
application/json
Wallet-signer id (wsg_…) of the current root admin to unseat in the same ceremony. Required when the root quorum is at capacity.
Pattern:
^wsg_[0-9A-Za-z]{22}$Example:
"wsg_034A1PiBr2b8JduxWEpO3E"
Response
Identifier for the roster-update ceremony; completion is reported via wallet_signer.promoted / wallet_signer.demoted webhooks.
Pattern:
^wcm_[0-9A-Za-z]{22}$⌘I
Promote a signer to admin (root seat swap)
curl --request POST \
--url https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '{}'import requests
url = "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote"
payload = {}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({})
};
fetch('https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.conduit.financial/v2/customers/{customerId}/wallet-signers/{signerId}/promote")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_body{
"ceremonyId": "<string>"
}{
"type": "INVALID_OID_FORMAT",
"title": "Invalid Object ID Format",
"status": 400,
"detail": "A path or query parameter expected a valid object identifier but received a value that does not match the expected format.",
"resolution": "Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'.",
"docs": "https://conduit-v2.mintlify.app/errors#invalid-oid-format",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "API_KEY_MISSING",
"title": "API Key Missing",
"status": 401,
"detail": "The request did not include an API key. All API requests must be authenticated.",
"resolution": "Include your API key in the 'x-api-key' header with every request.",
"docs": "https://conduit-v2.mintlify.app/errors#api-key-missing",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "API_KEY_READ_ONLY",
"title": "API Key Is Read-Only",
"status": 403,
"detail": "This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only.",
"resolution": "Use a read-write API key for this request, or have an organization admin mint one from the dashboard.",
"docs": "https://conduit-v2.mintlify.app/errors#api-key-read-only",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "SIGNER_NOT_FOUND",
"title": "Signer Not Found",
"status": 404,
"detail": "No signer exists with the specified ID for this wallet.",
"resolution": "Verify the signer ID is correct and that it belongs to the specified wallet.",
"docs": "https://conduit-v2.mintlify.app/errors#signer-not-found",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "IDEMPOTENCY_KEY_CONFLICT",
"title": "Idempotency Key Conflict",
"status": 409,
"detail": "The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original.",
"resolution": "Use a fresh idempotency key for the new request, or replay the original request unchanged.",
"docs": "https://conduit-v2.mintlify.app/errors#idempotency-key-conflict",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "UNSUPPORTED_MEDIA_TYPE",
"title": "Unsupported Media Type",
"status": 415,
"detail": "The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there.",
"resolution": "Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type.",
"docs": "https://conduit-v2.mintlify.app/errors#unsupported-media-type",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "SIGNER_PASSKEY_COUNT_TOO_LOW",
"title": "Signer Passkey Count Too Low",
"status": 422,
"detail": "Promotion to admin requires a passkey-credential signer to have at least 2 registered passkeys so they cannot lose admin access by losing a single device. Machine (api_key) admins do not need passkeys and are exempt (allowed only in the fully-automated signing mode).",
"resolution": "Have the passkey signer register a second passkey from a different device, then retry the promotion.",
"docs": "https://conduit-v2.mintlify.app/errors#signer-passkey-count-too-low",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}{
"type": "RATE_LIMITED",
"title": "Rate Limited",
"status": 429,
"detail": "Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses.",
"resolution": "Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact.",
"docs": "https://conduit-v2.mintlify.app/errors#rate-limited",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z",
"retryAfterSeconds": 3
}{
"type": "INTERNAL_ERROR",
"title": "Internal Error",
"status": 500,
"detail": "An unexpected error occurred while processing your request.",
"resolution": "Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation.",
"docs": "https://conduit-v2.mintlify.app/errors#internal-error",
"instance": "/v2/...",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}