Skip to main content

​
Environments

Conduit provides two environments. Both expose the same API and use the same authentication mechanism.
EnvironmentBase URLPurpose
Sandboxhttps://api.sandbox.conduit.financial/v2Integration development and testing
Productionhttps://api.conduit.financial/v2Live operations
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 the x-api-key header. 
curl https://api.conduit.financial/v2/customers \
  -H "x-api-key: ck_live_<64-hex-chars>"
Keys are prefixed to indicate their environment:
PrefixEnvironmentExample
ck_sandbox_Sandboxck_sandbox_aabbccdd...
ck_live_Productionck_live_aabbccdd...
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.

​
Access level

Each key is read-only or read-write:
Access levelAllowed requests
Read-onlyGET requests only. Any other method is rejected with 403 API_KEY_READ_ONLY.
Read-writeAll requests, including those that move money (payouts, order execution).
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.
API keys are shown once at creation and hashed server-side (SHA-256). Conduit cannot recover a lost key — revoke it and create a new one. When rotating a key, create the new key first, update your integration, then revoke the old key.

​
Request Headers

HeaderRequiredDescription
x-api-keyYesYour API key
Content-TypeYes (POST/PATCH)application/json for JSON bodies, multipart/form-data for file uploads
idempotency-keyYes on money-moving POSTs (orders, payouts, sender-information, execute, cancel). Optional on idempotent reads.Prevents duplicate operations on POST requests. Cached for 5 minutes.
x-client-correlation-idNoYour trace ID. Echoed back in the response for request correlation.
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 cache: The idempotency-key header is required on all money-moving POST requests. In both sandbox and production the cache TTL is 300 seconds (5 minutes). A replay of a successful request within that window returns the cached response, marked with an Idempotency-Replayed: true header; error responses are not cached, and a replay after expiry re-executes the request. Use crypto.randomUUID() (or uuidgen in bash) to generate a fresh key for each new operation. Rate limits. Responses on rate-limited routes carry X-RateLimit-Limit, 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 (order execute, document upload, application submit) carry tighter dedicated buckets (5 req/s, 10 burst on live). 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.

​
Errors

StatusMeaningWhat to do
400Validation failedCheck the errors array in the response body for field-level details
401Missing or invalid API keyVerify your x-api-key header
403ForbiddenA read-only key attempted a write (API_KEY_READ_ONLY), or your key’s organization cannot access the resource
404Resource not foundCheck the resource ID and ensure it belongs to your organization
409ConflictA resource with the same unique constraint already exists
429Rate limitedSlow down and retry after Retry-After seconds. See the Rate limits section above.
500Internal errorRetry with exponential backoff. If persistent, contact support with the x-correlation-id from the response