Authentication

TokenCashFlow supports two credential types depending on where your code runs.

Session tokens vs. API keys

Credential	Header	Use case
API key	X-API-Key: tcf_live_...	Server-to-server integrations; long-lived; create/revoke in portal

For merchant integrations, always use API keys.

API key authentication

Header format

X-API-Key: tcf_live_32randomcharactershere

Key lifecycle

1. Create a key in the Client Portal → Dashboard → API Keys (requires Basic KYC)
2. The full key is shown once at creation — copy it immediately
3. Keys are stored as SHA-256 hashes; TokenCashFlow cannot recover the original value
4. Revoke a key in the portal at any time — takes effect immediately
5. Create a new key before revoking an old one to avoid downtime
6. A maximum of 30 active keys is enforced per account

Key format

tcf_live_{random URL-safe characters}

Total length: ~41 characters. Only the first few characters (key_prefix) are retained for display once created.

KYC requirement

Creating payments, generating API keys, and requesting withdrawals require at least Basic KYC. If your KYC has not been approved, the API returns:

{
  "success": false,
  "data": null,
  "error": {
    "code": "KYC_REQUIRED",
    "message": "Basic KYC approval is required for this operation.",
    "details": {}
  }
}

HTTP status: 403 Forbidden

Complete KYC in the Client Portal → Dashboard → Identity Verification.

Rate limits

Scope	Default limit	Response on exceeded
Per API key	60 requests/second	429 Too Many Requests

On rate-limit hit, the response includes a Retry-After: 1 header (1-second tumbling window).

Recommended back-off strategy:

import time, random

def request_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 1))
        jitter = random.uniform(0, 0.5)
        time.sleep(retry_after + jitter)
    raise Exception("Rate limit retries exhausted")

Security best practices

• Never expose your API key in frontend code (JavaScript, HTML, mobile app bundles). API keys are for server-side use only.
• Store keys as environment variables, not in source code.
• Rotate keys immediately if you suspect compromise: create a new key, deploy it, then revoke the old one.
• Use a separate key per environment (staging, production).
• Monitor last_used_at in the portal to detect unexpected key usage.