Environments
Conduit provides two environments. Both expose the same API and use the same authentication mechanism.
Sandbox is available immediately after sign-up — generate a sandbox key and start integrating right away. Production access requires completing Conduit’s organization onboarding and activation process; once your organization is activated, switch the dashboard toggle to live and generate live keys.
API Keys
All requests require an API key passed in thex-api-key header.
The prefix is validated on every request. A
ck_sandbox_ key presented to the production API (or vice versa) is rejected with 401 API_KEY_INVALID. Keys are scoped to a single organization and environment. Generate and revoke keys from the Conduit dashboard. Removing a team member from your organization also stops every key that member created.
Access level
Each key is read-only or read-write:
You choose the access level when creating a key in the dashboard; new keys are read-only by default. A key’s access level is fixed for its lifetime — to change it, revoke the key and create a new one. Use read-only keys for reporting and reconciliation integrations that never need to write.
Request Headers
Conduit also returns an
x-correlation-id header on every response — a server-generated trace ID useful for support requests.
Sandbox-specific behavior
Use your sandbox API key (ck_sandbox_...) against https://api.sandbox.conduit.financial. Sandbox and production keys are not interchangeable — a production key on the sandbox host returns 401 API_KEY_INVALID.
Idempotency: The idempotency-key header is required on the endpoints that the API reference marks with it. These include orders, payouts, wallets, registered addresses, whitelist recipients, onboarding, feature applications, RFI responses and customer updates. A request without the header returns 400 IDEMPOTENCY_KEY_REQUIRED. Every other POST, PATCH and PUT endpoint accepts the header, and replay protection applies to it in the same way. POST /v2/quotes and POST /v2/payouts/requirements refuse the header with 400 VALIDATION_ERROR, because a replay on them must always reprice or re-evaluate. In both sandbox and production a successful response is kept for 30 days. A retry with the same key returns that original response, marked with an Idempotency-Replayed: true header, and reusing the key with a different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Error responses are not kept. After the operation itself ends in a 4xx, the same key is accepted again, with the same body or a corrected one; IDEMPOTENCY_KEY_CONFLICT and IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS change nothing about the key. After a 5xx, the same body runs again and a different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Use crypto.randomUUID() (or uuidgen in bash) to generate a fresh key for each new operation.
Rate limits. Once your API key is accepted, every response carries X-RateLimit-Limit (the size of the bucket the request counted against), X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the bucket refills). These headers are present on both successful responses and 429 errors; they are omitted only when the rate-limit service is temporarily unreachable and the request is allowed through anyway. When a request exceeds the limit you receive 429 RATE_LIMITED with a Retry-After header and a retryAfterSeconds body field; sleep that many seconds then retry. Limits use a token bucket: live keys get 50 requests/second sustained with a burst of 100; sandbox is more permissive (200 req/s sustained, 400 burst). Per-organization overrides are available through your support contact when your sustained workload exceeds the defaults. A handful of expensive endpoints carry a tighter dedicated bucket (5 req/s, 10 burst, in live and sandbox alike): POST /v2/orders/{orderId}/execute, POST /v2/documents, and POST /v2/onboarding together with POST /v2/customers/{customerId}/updates. Order execute, document upload and application submit each have their own bucket, counted apart from the general one, so X-RateLimit-Limit reads 10 there and, by default, 100 (live) or 400 (sandbox) elsewhere.
Cross-environment errors: A 401 API_KEY_INVALID against the sandbox base URL means you are using a live key, not a sandbox key. If your sandbox key is valid but your organization’s sandbox environment has not been provisioned yet, you receive 409 SANDBOX_NOT_PROVISIONED (not a 401) — provisioning happens automatically after sign-up and is retried, so wait a few moments and retry; contact support if it persists. Do not rotate or regenerate the key for this case — the key is valid.