API keys

API keys authenticate server-side requests to the CashXChain API. Keys are environment-scoped and type-gated — the type determines what operations the key may perform.

---

Key types

Secret key (sk_)

The default all-purpose server-side key. Suitable for backend integrations where you fully control the runtime environment.

• Full read + write access to all /v1/* routes.
• Scope array is accepted at creation but ignored at runtime — a sk_ key always passes scope checks.
• Cannot access dashboard (/internal/*) routes.

Publishable key (pk_)

A read-only key safe to embed in front-end or mobile applications.

• GET, HEAD, and OPTIONS requests only — any write method (POST, PUT, DELETE, PATCH) returns 403 Forbidden.
• Write scopes are stripped silently at creation even if submitted.
• Cannot access dashboard routes.

Restricted key (rk_)

A scoped key for least-privilege integrations. Only routes matching the declared scopes are accessible.

• Read and/or write access, limited to scopes declared at creation.
• A handler requiring payments:write returns 403 if that scope is absent from the key.
• Cannot access dashboard routes.

Master key (mk_) — Platform / operations

The highest-privilege credential. Not a developer key — a platform operations credential.

• Full access to all /v1/* and /internal/* (dashboard) routes.
• Bypasses all scope checks.
• Cannot be created via the API. Provisioned only by running the admin seed script with direct database access.
• Cannot be revoked via the API. Revocation requires direct database intervention.
• Stored in a separate master_keys table; the api_keys table is never touched.

Use master keys only for internal dashboards, ops tooling, and platform-level automation. Never distribute them to third-party integrations — issue a sk_ or rk_ key instead.

---

Environments

Keys are environment-scoped and will be rejected if used against the wrong environment.

Environment	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. Never commit keys to source control.

---

Key format

{prefix}{64 hex characters}

Total length: 75 characters. The 64-character random suffix provides 256 bits of entropy. Only the SHA-256 hash of the full key is stored — the plain-text token is shown once at creation and is never recoverable.

---

Creating a key

Requires a valid bearer credential (JWT or existing API key).

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

Secret key

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

Publishable key

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

Restricted key

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

Response (201 Created)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object": "api_key",
  "name": "Backend production",
  "token": "sk_sandbox_ab12cd34ef56gh78...",
  "prefix": "sk_sandbox_ab12cd34",
  "last4": "a1b2",
  "type": "secret",
  "scopes": [],
  "created_at": "2026-06-08T00:00:00Z"
}

Copy the token field immediately. It is not stored and cannot be retrieved after this response.

---

Available scopes

Request only the scopes your integration needs.

Scope	Grants
transfers:read	List and retrieve transfers
transfers:write	Create transfers
transactions:read	List and retrieve transactions
contacts:read	List contacts / payment beneficiaries
payments:read	List and retrieve payments
payments:write	Create payments (add-funds, send, FX execute)
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

sk_ and mk_ keys bypass all scope checks. Scopes only gate pk_ and rk_ keys.

---

Listing keys

GET /v1/api-keys
Authorization: Bearer <token>

Returns an array of key objects. The token field is never included in list responses — only prefix and last4 are returned for masked display.

---

Revoking a key

DELETE /v1/api-keys/{id}
Authorization: Bearer <token>

Returns 204 No Content. Revocation is immediate and permanent — the key hash is retained in the database for audit purposes but cannot be used for authentication.

---

Key rotation

Rotate keys regularly and immediately after any suspected exposure.

Recommended rotation process:

1. Create a new key with the same type and scopes.
2. Deploy the new key to your secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, etc.).
3. Confirm successful API calls using the new key.
4. Revoke the old key via DELETE /v1/api-keys/{id}.
5. Review GET /v1/request-logs for unexpected usage of the old key.

---

Security requirements

• Store keys only in server-side secret storage — never in environment variable files committed to git.
• Do not log or print key values in application code or CI pipelines.
• Do not expose sk_ or rk_ keys in browser JavaScript or mobile apps — use pk_ for client-side reads.
• Revoke unused or rotated keys promptly.
• Monitor GET /v1/request-logs for unexpected authentication failures.

---

Compromised keys

If you suspect a key has been exposed:

1. Revoke it immediately via DELETE /v1/api-keys/{id}.
2. Rotate all dependent services to a new key.
3. If a production payment-capable key (sk_live_ or rk_live_ with payments:write) was exposed, contact [email protected].