API Keys & Authentication
How do I authenticate against the API?
Create an API key in the dashboard (or via POST /api/v1/api-keys) and send it as a bearer token:
curl "https://api.certwatch.io/api/v1/certificates" \
-H "Authorization: Bearer cw_live_..."
Keys are organization-bound: a key can only see and modify its own organization’s data. No default key is created for new accounts, so you create your first key yourself.
What permissions can a key have?
A key carries either admin (all HTTP methods: GET, POST, PUT, DELETE) or read (GET only). Use read-only keys wherever you can. A read-only key used for a write returns 403 METHOD_NOT_ALLOWED.
Can I restrict where a key is used from?
Yes. Keys support an IP whitelist with individual IPv4/IPv6 addresses and CIDR ranges, plus an optional expiration timestamp. Requests from non-whitelisted IPs are rejected.
How do I rotate a key?
POST /api/v1/api-keys/{id}/rotate issues a new secret and immediately invalidates the old one. Update your clients first, then rotate. Rotating every 90 days is recommended.
What are the rate limits?
Rate limits apply per API key, per minute, by endpoint group:
| Endpoint group | Requests/minute |
|---|---|
| Certificates, Uptime | 100 (bulk endpoints exempt) |
| Analytics, Alerts, Subdomain discovery | 50 |
| API keys | 60 |
| Audit logs, Organizations, Alert rules, Billing, Notification channels | 30 |
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. On 429, respect the retry_after value and back off.
What is the difference between dashboard login and API keys?
The dashboard authenticates users with a session (Clerk); the API authenticates machines with API keys. Both resolve to the same organization and honor the same role and permission rules. Dashboard sessions are not rate-limited; API keys are.
Is API usage audited?
Yes. Every request is written to the audit log with method, path, status, authentication context, IP, and the action performed. See Audit Logs for the full field reference and how to query or export them.