Authentication Reference

Two credential types

Credential	Header	Lifetime	Use case
API key	X-API-Key: tcf_live_...	Until revoked	Server-to-server integrations

API key header

X-API-Key: tcf_live_32randomcharactershere

On each request, TokenCashFlow:

1. Enforces a per-key rate limit (default 60 requests/second; Redis 1-second tumbling window keyed by a hash of the key)
2. Hashes the provided key with SHA-256
3. Looks up the hash in the api_keys table
4. If found and status = active: processes the request in the context of the key's owner
5. Records last_used_at

API keys are accepted on: POST/GET /v1/payments*, GET /v1/payments/tokens, GET/PUT /v1/payments/settings, and all /v1/withdrawals* endpoints — the surface you need for a server-side integration.

Error responses

Scenario	HTTP Status	Error code
No credential provided	401	UNAUTHORIZED
Invalid / revoked key	401	UNAUTHORIZED
Valid credential but insufficient permissions	403	FORBIDDEN
Valid credential but KYC not approved	403	KYC_REQUIRED

Example 401 response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "details": {}
  }
}

Example 403 KYC_REQUIRED response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "KYC_REQUIRED",
    "message": "KYC verification required (level: basic).",
    "details": {}
  }
}

KYC-gated endpoints

The following operations require at least Basic KYC:

• POST /v1/payments — create a payment
• POST /v1/api-keys — create an API key
• POST /v1/withdrawals/request — request a withdrawal

The following require Advanced KYC to unlock (e.g. removal of the Basic-KYC daily withdrawal cap):

• Unlimited daily withdrawal volume (Basic KYC accounts are capped at the operator-configured rolling 24-hour limit, default $50,000)