Authentication
API keys, scopes, and modes.
The EzPays Public API authenticates every request with a secret API key passed as a Bearer token.
Sending the credential
GET /api/public/v1/payment-links HTTP/1.1
Host: api.ezpays.app
Authorization: Bearer ezp_live_<32 base62 chars>Requests without a valid Authorization header receive 401 Unauthorized.
Key format
| Component | Value |
|---|---|
| Prefix | ezp_ |
| Mode | live_ (production) or test_ (sandbox) |
| Secret | 32 random base62 characters |
Examples:
ezp_live_2g8f4mZkQp...— production keyezp_test_xR3aLm0vJ7...— test key
The full secret is shown once at creation time; only a 14-character prefix and a SHA-256 hash are persisted on our side.
Modes — live vs. test
Both modes share the same API surface, schemas, and response shapes:
| Live mode | Test mode | |
|---|---|---|
| Prefix | ezp_live_ | ezp_test_ |
| Payment provider | Real PSP (e.g. Stripe, Mercado Pago) | Sandboxed simulator |
| Webhook deliveries | Real HTTPS endpoints | Real HTTPS endpoints |
| Data | Production tenants & creditors | Production tenants & creditors |
| Cross-talk | None — test keys cannot read or mutate live resources, and vice versa |
You can develop and test against ezp_test_ indefinitely without any risk to production data.
Scopes
Each key is granted one or more scopes at creation time. A request that exceeds the key's scopes returns 403 Forbidden with {"error":{"code":"forbidden","message":"Missing required scope: ..."}}.
| Scope | Allows |
|---|---|
payments:read | Read payment links and their settlements. |
payments:write | Create, cancel, and regenerate payment links. |
recovery:read | Read recovery cases, debts, and payments. |
recovery:write | Create cases and trigger lifecycle actions. |
recovery:import | Submit bulk debt imports. |
webhooks:manage | Manage outbound webhook endpoints (admin UI only — no public endpoint). |
Apply the principle of least privilege: a backend that only generates payment links should be granted payments:write (and optionally payments:read), not all scopes.
Rotating and revoking
- Rotate: create a new key, deploy it, then revoke the old one.
- Revoke: deleting a key in the dashboard takes effect within seconds (cached at most one minute on edge).
- Audit: every authenticated request is recorded with the key's prefix, IP, and request ID.
Storage best practices
- Inject keys via environment variables or a secret manager — never hard-code them.
- Use distinct keys per service so you can rotate without coordination.
- Restrict scopes per key.
- Rotate periodically (every 90 days is a reasonable cadence).