Skip to main content

​
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.
PrefixModeNetwork
zfi_test_TestSolana Devnet
zfi_live_LiveSolana 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 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 -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 -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

Keys are hashed with both SHA-256 (for fast lookup) and Argon2 (for breach resistance) before being stored. ZendFi never stores plaintext keys.
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.
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.
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 CategoryLimitWindow
Payment creation50 requests1 hour
Dashboard / reads200 requests1 hour
All other endpoints100 requests1 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.