Authentication

The FYATU CaaS API v3.20 uses API key authentication — no tokens to exchange, no JWTs to decode. Every request must include a valid API key, and the key’s scopes determine what the request is allowed to do.

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   Your server                FYATU CaaS API                        │
│                                                                     │
│   GET /cardholders  ──────────────────────────────────────────────► │
│   Authorization: Bearer fyatu_live_abc123...                        │
│                                                                     │
│                       ① Validate key (SHA-256 hash lookup)         │
│                       ② Check key status (ACTIVE / REVOKED)        │
│                       ③ Check IP allowlist (if configured)         │
│                       ④ Check business status (ACTIVE)             │
│                       ⑤ Sliding-window rate limit (1,000/min)      │
│                       ⑥ Enforce scope (cardholders:read)           │
│                                                                     │
│                ◄──────────────────────────────────────────────────  │
│   200 OK + cardholder list                                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Getting Your API Key

Open the CaaS portal

Go to platform.fyatu.com and log in to your CaaS account.

Navigate to API Keys

Click Developer → API Keys in the left sidebar.

Create an API key

Click Create API Key. Name the key, choose its environment (LIVE or SANDBOX), and select the scopes it needs.

Copy the key immediately

The full key is shown once at creation time. Copy it to your secrets manager now — it cannot be retrieved later.

API keys are shown once at creation. If you lose a key, revoke it and create a new one. Never log keys or commit them to version control.

Sending the API Key

Pass your key in the Authorization header as a Bearer token. This is the only supported method.

curl -X GET https://api.fyatu.com/api/v3.20/cardholders \
  -H "Authorization: Bearer fyatu_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234"

const response = await fetch('https://api.fyatu.com/api/v3.20/cardholders', {
  headers: {
    'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

import os, requests

resp = requests.get(
    'https://api.fyatu.com/api/v3.20/cardholders',
    headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'}
)

req, _ := http.NewRequest("GET", "https://api.fyatu.com/api/v3.20/cardholders", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("FYATU_API_KEY"))
resp, _ := http.DefaultClient.Do(req)

$ch = curl_init('https://api.fyatu.com/api/v3.20/cardholders');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FYATU_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$resp = json_decode(curl_exec($ch), true);

Authentication Failure Response

When authentication fails, the API returns an error using the standard response envelope:

401 — Invalid API key

{
  "success": false,
  "status": 401,
  "message": "API key is invalid or does not exist",
  "error": {
    "code": "API_KEY_INVALID",
    "detail": "The provided API key was not found in this environment"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

403 — Insufficient scope

{
  "success": false,
  "status": 403,
  "message": "API key does not have the required scope",
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "detail": "This endpoint requires the cards:write scope"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

Environment Isolation

Each API key is bound to a single environment. Keys issued for SANDBOX only work against sandbox data; LIVE keys only against live data. The environment is enforced server-side — you cannot mix data between environments and attempting to do so returns API_KEY_INVALID.

Environment	Purpose
`SANDBOX`	Development and testing. No real card issuance. KYC completes in seconds.
`LIVE`	Production. Real cardholders, real cards, real transactions.

Always build and test against SANDBOX before switching to LIVE. The two environments have separate programs, cardholders, and cards — nothing carries over.

Scopes

API keys are scoped to specific resource permissions. A key without a scope cannot call endpoints that require it — it receives a 403 INSUFFICIENT_SCOPE response. Assign only the scopes your integration actually needs.

Scope	What It Grants
`cardholders:read`	`GET /cardholders`, `GET /cardholders/{id}`
`cardholders:write`	`POST /cardholders`, `PATCH /cardholders/{id}`, `POST /cardholders/{id}/suspend`, `POST /cardholders/{id}/reactivate`
`cards:read`	`GET /cards`, `GET /cards/{id}`
`cards:write`	`POST /cards`, `POST /cards/{id}/freeze`, `POST /cards/{id}/unfreeze`, `POST /cards/{id}/terminate`, `POST /cards/{id}/fund`, `POST /cards/{id}/unload`
`transactions:read`	`GET /transactions`, `GET /transactions/{id}`
`webhooks:read`	`GET /webhooks`, `GET /webhooks/{id}`
`webhooks:write`	`POST /webhooks`, `PATCH /webhooks/{id}`, `DELETE /webhooks/{id}`

Create separate keys for separate services. A read-only reporting service should only have *:read scopes. A compromised minimal-scope key limits the blast radius.

Idempotency-Key Header

For write operations (POST), you can supply an Idempotency-Key header to safely retry requests without risking duplicate operations.

curl -X POST https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ.../fund \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fund-card-crd01HXYZ-order-9991" \
  -d '{ "amount": 50.00 }'

How it works:

If a request with the same Idempotency-Key is received within 24 hours, the API replays the original response without re-executing the operation.
Replayed responses include the header Idempotency-Replayed: true.
Keys must be unique strings of up to 255 characters. A UUID or a deterministic hash of your operation parameters works well.
After 24 hours, the key expires and a request with the same key is treated as a new operation.

# Replayed response headers
Idempotency-Replayed: true

If you send the same Idempotency-Key with a different request body, the API returns 422 IDEMPOTENCY_KEY_TOO_LONG if the key is malformed, or 409 CONFLICT if the body does not match the original request.

When to use it: Fund card, create cardholder, issue card, and any write operation that should not be duplicated if your network times out and you retry.

Rate Limits

The CaaS API enforces a sliding-window rate limit of 1,000 requests per minute per API key. Every response includes rate-limit headers:

Header	Description
`X-RateLimit-Limit`	Your key’s request cap per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you exceed the limit, the API returns 429 RATE_LIMITED. Implement exponential backoff:

async function withBackoff(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const resetAt = res.headers.get('X-RateLimit-Reset');
    const wait = resetAt
      ? (Number(resetAt) * 1000 - Date.now())
      : (2 ** attempt * 1000);
    await new Promise(r => setTimeout(r, Math.max(wait, 1000)));
  }
  throw new Error('Rate limit retries exhausted');
}

IP Allowlisting

API keys can optionally restrict which IP addresses may use them. If you configure an IP allowlist in the portal and a request arrives from an unlisted IP, the API returns 403 IP_NOT_ALLOWED. This is strongly recommended for server-to-server LIVE integrations. Leave the allowlist empty during development or when your server IPs are dynamic.

Authentication Error Reference

Code	HTTP	Cause
`API_KEY_INVALID`	401	Key does not exist in this environment or is malformed
`API_KEY_REVOKED`	401	Key was explicitly revoked in the portal
`API_KEY_EXPIRED`	401	Key passed its expiry date
`IP_NOT_ALLOWED`	403	Client IP is not in the key’s allowlist
`BUSINESS_SUSPENDED`	403	Business account is suspended
`BUSINESS_CLOSED`	403	Business account is permanently closed
`INSUFFICIENT_SCOPE`	403	Key does not have the required scope
`RATE_LIMITED`	429	Request rate exceeded

Best Practices

Store keys in secrets managers

Never hard-code API keys in source files. Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler, etc.). Rotate keys at least every 90 days.

Use separate keys per service

Issue one key per microservice or integration, each with the minimal required scopes. This lets you revoke a single key without disrupting other services.

Configure IP allowlisting for LIVE

For production workloads, set an IP allowlist on your LIVE API keys. This adds a layer of defense even if a key is leaked — the attacker cannot use it from an unlisted IP.

Use Idempotency-Key on all write operations

Network failures happen. Always supply Idempotency-Key on fund, issue, and create requests so a retry never double-charges your program balance.

Monitor your rate limit headers

Log X-RateLimit-Remaining on every response. If it consistently approaches zero, batch requests, cache reads, or contact support to request a higher rate limit.

Getting Started

Concepts

Authentication

Authentication

How It Works

Getting Your API Key

Sending the API Key

Authentication Failure Response

Environment Isolation

Scopes

Idempotency-Key Header

Rate Limits

IP Allowlisting

Authentication Error Reference

Best Practices

​Authentication

​How It Works

​Getting Your API Key

​Sending the API Key

​Authentication Failure Response

​Environment Isolation

​Scopes

​Idempotency-Key Header

​Rate Limits

​IP Allowlisting

​Authentication Error Reference

​Best Practices

Authentication

How It Works

Getting Your API Key

Sending the API Key

Authentication Failure Response

Environment Isolation

Scopes

Idempotency-Key Header

Rate Limits

IP Allowlisting

Authentication Error Reference

Best Practices