Partner API key authentication, scopes, and security practices.
Partner API requests authenticate with an API key, not a staff JWT.
Header
X-API-Key: clfy_test_xxxxxxxxxxxxxxxx
Keys are issued in the Cladfy admin under Developers → API Keys. The full secret is shown once at create or regenerate.
Key formats
| Prefix | Environment |
|---|---|
clfy_test_ | Test / sandbox |
clfy_live_ | Live / production data |
Scopes
Keys may be limited to scopes such as clients:read, loans:write, portal:read, or * (all). Missing scopes return 403 with a clear error code.
Tenant binding
The tenant slug in the URL must match the key’s tenant. Cross-tenant keys are rejected.
Portal borrower scope
For /portal/* routes in live mode, also send:
X-Client-Id: {borrower-client-uuid}
(or client_id query). Test mode uses fixtures and does not require this header.
Security practices
- Store keys only on your server.
- Never ship keys in mobile apps, SPAs, or public repos.
- Rotate via Regenerate (email OTP) if compromised.
- Prefer least-privilege scopes.
Errors
| HTTP | Typical cause |
|---|---|
| 401 | Missing / invalid key |
| 403 | Wrong tenant or missing scope |
| 429 | Rate limit exceeded |