Authentication

All API requests must include an Authorization header with a bearer token.

Authorization: Bearer sk_sandbox_...

---

API key types

CashXChain issues three types of API keys. Each has a distinct prefix and a different permission level.

Secret key — sk_

The standard server-side key. Use it for all backend integrations.

• Full read and write access to all /v1/* routes.
• Never expose in client-side code, mobile apps, or public repositories.

Publishable key — pk_

A read-only key safe for use in front-end or mobile environments.

• Read access only (GET requests). Any write request returns 403 Forbidden.
• Suitable for displaying balances, transaction history, or FX rates in a UI.

Restricted key — rk_

A scoped key for least-privilege integrations.

• Access limited to the specific scopes declared when the key was created.
• Use when issuing keys to services that only need a subset of your API access.

Master key / Platform key — mk_

A master key provides unrestricted access to all API routes, including platform-level and dashboard endpoints not reachable by standard API keys. It is intended for platforms and operators building on top of CashXChain infrastructure.

Master keys are not self-serve. To request one, contact [email protected] with your use case. CashXChain provisions the key directly to your account.

---

Environments

Environment	Key prefix
Sandbox	sk_sandbox_, pk_sandbox_, rk_sandbox_, mk_sandbox_
Production	sk_live_, pk_live_, rk_live_, mk_live_

Never use production keys in local development or non-production environments.

---

Scopes

Scopes apply to restricted keys only. Secret keys have full access regardless of the scope list.

Scope	Access granted
transfers:read	List and retrieve transfers
transfers:write	Create transfers
transactions:read	List and retrieve transactions
contacts:read	List contacts
payments:read	List and retrieve payments
payments:write	Create payments and execute FX conversions
fx:read	Create persisted FX quotes
api_keys:read	List API keys
api_keys:write	Create and revoke API keys
request_logs:read	Access request logs
usage:read	Access usage analytics

Request only the scopes your integration needs. Scopes are declared at key creation and cannot be changed afterwards — create a new key if you need different scopes.

---

Creating a key

POST /v1/api-keys
Authorization: Bearer <existing-key>
Content-Type: application/json
Idempotency-Key: <uuid>

Secret key:

{
  "name": "Backend service",
  "type": "secret"
}

Restricted key:

{
  "name": "Payments service",
  "type": "restricted",
  "scopes": ["payments:read", "payments:write"]
}

Publishable key:

{
  "name": "Dashboard read-only",
  "type": "publishable"
}

The response includes a token field with the full key value. This is shown once only — copy it immediately and store it in a secret manager. It cannot be retrieved again.

---

Key rotation

1. Create a new key with the same type and scopes.
2. Deploy the new key to your environment.
3. Confirm API calls succeed with the new key.
4. Revoke the old key: DELETE /v1/api-keys/{id}.
5. Check GET /v1/request-logs for any unexpected usage of the old key.

---

Authentication errors

Status	Code	Meaning
401	authentication_required	No Authorization header provided.
401	invalid_api_key	Key not found or revoked.
403	insufficient_scope	Restricted key is missing the required scope.
403	publishable_key_write_denied	Publishable key attempted a write request.
403	environment_mismatch	Key environment does not match the API base URL.

---

Security checklist

• Store keys in a secret manager — not in environment files committed to source control.
• Do not log or print key values in application code or CI pipelines.
• Use the most restrictive key type that satisfies your use case.
• Rotate keys regularly and immediately after any suspected exposure.
• Revoke keys that are no longer in use.