Authentication
API keys, permissions, IP allowlists, and keeping your key safe.
Every request is authenticated with a Bearer token:
curl https://api.disputely.com/v1/alerts \
-H "Authorization: Bearer dspm_live_YOUR_KEY"Keys
Merchant API keys start with dspm_live_. You create and revoke them yourself
in Settings → API in the Disputely dashboard.
- The full key is shown once, at creation. We store only a hash, so a lost key can't be recovered — revoke it and create a new one.
- Keys never expire on their own. Revoke a key at any time; it stops working immediately.
- You can have up to 10 active keys. Use one per environment or service so you can revoke them independently.
Keep keys server-side
Never put an API key in a browser, mobile app, or public repo. Load it from an environment variable or secrets manager on your backend.
Permissions
You choose what each key can do when you create it:
| Permission | Allows |
|---|---|
alerts:read | List and read alerts. |
alerts:write | Resolve alerts — tells the card network you refunded. Off by default. |
resolve_lookups:read | List lookups (bank inquiries about your charges). |
Give keys the minimum they need. A dashboard that only displays alerts doesn't
need alerts:write.
IP allowlist (optional)
When creating a key you can restrict it to specific IPs or CIDR ranges
(e.g. 203.0.113.10/32). Requests from anywhere else are rejected with
401 ip_not_allowed. Leave it empty to allow all IPs.
Auth errors
| HTTP | code | Meaning |
|---|---|---|
| 401 | missing_credentials | No Authorization header. |
| 401 | invalid_credentials | Key not recognized. |
| 401 | key_revoked | Key was revoked. |
| 401 | ip_not_allowed | Request came from an IP outside the key's allowlist. |
| 403 | insufficient_scope | Key is valid but lacks the required permission. |
See Errors for the error body shape.