API Keys

Create, list, and rotate your merchant API keys.

API Keys

API keys authenticate all requests to the ZendFi API. Each key is scoped to either test or live mode, and the prefix tells you which environment it targets.

Prefix	Mode	Network
zfi_test_	Test	Solana Devnet
zfi_live_	Live	Solana Mainnet

List API Keys

GET /api/v1/keys

Returns all API keys for the authenticated merchant. The actual key values are never returned — only metadata.

Response

[
  {
    "id": "key_abc123",
    "mode": "test",
    "is_active": true,
    "created_at": "2026-03-01T12:00:00Z",
    "last_used_at": "2026-03-05T09:30:00Z"
  },
  {
    "id": "key_def456",
    "mode": "live",
    "is_active": true,
    "created_at": "2026-03-01T12:00:00Z",
    "last_used_at": null
  }
]

cURL

curl https://api.zendfi.tech/api/v1/keys \
  -H "Authorization: Bearer zfi_test_your_key"

---

Create an API Key

POST /api/v1/keys

Generates a new API key. The key value is returned only once in the response — store it securely.

mode · string · required

Either test or live.

Example

cURL

curl -X POST https://api.zendfi.tech/api/v1/keys \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"mode": "test"}'

Response

{
  "key": "zfi_test_a1b2c3d4e5f6...",
  "id": "key_ghi789",
  "mode": "test",
  "created_at": "2026-03-05T14:00:00Z"
}

The key field is only included in the create response. There is no way to retrieve it later. If you lose it, rotate the key to generate a new one.

---

Rotate an API Key

POST /api/v1/keys/{id}/rotate

Deactivates the specified key and generates a replacement. The old key stops working immediately, and the new key is returned in the response.

id · string · required

API key ID to rotate.

cURL

curl -X POST https://api.zendfi.tech/api/v1/keys/key_abc123/rotate \
  -H "Authorization: Bearer zfi_test_your_key"

Response

{
  "old_key_id": "key_abc123",
  "old_key_deactivated": true,
  "new_key": "zfi_test_x9y8z7w6v5u4...",
  "new_key_id": "key_jkl012",
  "mode": "test",
  "created_at": "2026-03-05T14:30:00Z"
}

---

Key Security

Storage

Keys are hashed with both SHA-256 (for fast lookup) and Argon2 (for breach resistance) before being stored. ZendFi never stores plaintext keys.

Environment Variables

Always store keys in environment variables or a secrets manager. Never commit them to source control. Use .env files locally and your platform’s secrets management in production.

Key Rotation

Rotate keys regularly and immediately if a key may have been exposed. Rotation is atomic — the old key is deactivated the moment the new one is created.

Mode Isolation

Test keys cannot access live data and vice versa. This prevents accidental production charges during development.

Rate Limits

API keys are rate-limited per merchant:

Endpoint Category	Limit	Window
Payment creation	50 requests	1 hour
Dashboard / reads	200 requests	1 hour
All other endpoints	100 requests	1 hour

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709298300

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.