Security and keys
How API keys are protected, what a key can never do, per-key controls (scopes, IP allowlist, spend caps, expiry), and what to do if a key leaks.
The Partner API was designed on the assumption that a key can be stolen and that the platform calling it can be compromised. This article explains what is enforced on our side and what we recommend on yours.
What a key can never do
Regardless of its scopes, a key cannot:
- Read anyone else's orders, or any user data beyond the key owner's own name and email.
- Add, withdraw or move wallet funds. It can only spend the owner's balance, and only within the key's per-order and 24-hour caps.
- Create, list or revoke keys, change the account, or reach any other LinkWatcher feature.
- Bypass the marketplace rules (eligibility, word counts, publisher availability).
How it is enforced
- API requests run against our database as a dedicated role with no table access at all, only the handful of functions behind these endpoints. Every function re-checks the key owner inside the database, so a bug in the API layer cannot widen what a key can reach.
- Keys are hashed at rest and compared by hash. Unknown keys are rate limited per IP.
- Every order is validated, priced, cap-checked and paid inside one database transaction. A failed check leaves nothing behind: no pending order, no charge.
- HTTPS is required, responses are never cached, and error messages never echo your input or internals.
- Creating a key, revoking a key, and enabling or disabling API access always email the account owner.
Per-key controls
| Control | What it does | Our recommendation |
|---|---|---|
| Scopes | catalog:read, orders:read, orders:write. Write is opt-in. | Give orders:write only to the service that places orders. |
| IP allowlist | Requests from other addresses are rejected with 403 ip_not_allowed. | Set it on every orders:write key to your servers' egress IPs. |
| Max amount per order | Orders above it are refused (403 order_cap_exceeded). | Keep it at the largest listing you actually sell. |
| Spend cap per 24 hours | Rolling window over orders paid with the key (403 daily_cap_exceeded). | Keep it close to your real daily volume; raise it when you grow. |
| Expiry | 30 or 90 days, 1 year, or never. | 1 year, with rotation. |
Recent activity
The API Access page lists security events for your keys: key created, key revoked, requests blocked by the IP allowlist or a missing scope, expired-key attempts, orders placed, and cap hits. Blocked requests and cap hits are early warnings that a key is being misused.
Rotation
Create the new key, deploy it, confirm traffic on the new key (Last used), then revoke the old one. You can hold up to 5 active keys, so overlap is easy.
If a key leaks
- Revoke it on the API Access page. Requests using it fail within seconds with 401
api_key_revoked. - Create a new key with an IP allowlist and lower caps.
- Review your orders in the dashboard. Email support@linkwatcher.io if you see orders you did not place.
- If you cannot reach the dashboard, ask support to disable API access for the whole account; that revokes every key at once.
When a Marketplace Enterprise subscription ends, every key stops working at the end of the paid period (401 api_access_disabled). Keys are kept, so resubscribing restores them without changes on your side.