Authentication

Rach CaaS uses two distinct authentication schemes depending on the endpoint type.

---

API Key Authentication (B2B Endpoints)

All B2B endpoints — /v1/users/*, /v1/transfers/*, /v1/fx/* — require an API key passed as a request header.

Header name: X-API-Key

POST /v1/users/provision HTTP/1.1
Host: rach-caas-api-dx75yvdhaq-nw.a.run.app
X-API-Key: rach_sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Key Prefixes

Prefix	Environment	Behaviour
rach_sk_live_*	Production (mainnet)	Real on-chain execution on Polygon PoS
rach_sk_test_*	Sandbox	Returns SANDBOX_SIMULATED — no blockchain, no balance debit

Managing API Keys

API keys are created and revoked through the Dashboard API (JWT-authenticated):

• POST /v1/dashboard/apikeys — generate a new key
• GET /v1/dashboard/apikeys — list active keys
• DELETE /v1/dashboard/apikeys/{id} — hard-revoke a key

⚠️ The key_secret value is returned only once at creation. Store it securely in a secrets manager (e.g. GCP Secret Manager, AWS Secrets Manager, Vault).

---

JWT Bearer Authentication (Dashboard Endpoints)

Dashboard endpoints — /v1/dashboard/* — require a JWT Bearer token issued by the Rach payments platform.

Header name: Authorization
Format: Bearer <token>

GET /v1/dashboard/metrics HTTP/1.1
Host: rach-caas-api-dx75yvdhaq-nw.a.run.app
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Required JWT Claims

Claim	Description
business_id (or org_id)	Your tenant's unique identifier
waas	Must be present in the permissions field

Contact support@rach.finance to obtain your JWT credentials.

---

Error Responses

HTTP Status	Meaning
401 Unauthorized	Missing or invalid API key / JWT
403 Forbidden	Valid credentials but insufficient permissions (e.g. non-super-admin calling admin endpoints)

{
  "error": "invalid_api_key",
  "message": "The provided X-API-Key is not recognized."
}