Get started
Authentication
Every redaction, restore and account call needs an API key in the x-api-key header.
curl -s https://api.obscate.com/v1/usage -H "x-api-key: $OBSCATE_API_KEY"
Key format
Keys look like ob_7d3nmlvc_ followed by 43 random characters: ob_, an 8-character public prefix, an underscore, and the secret. The prefix is safe to show in dashboards and logs (ob_7d3nmlvc_…) so you can tell keys apart. The rest is the secret.
Shown once
- A key is returned exactly once, by
POST /v1/signuporPOST /v1/keys. Copy it then. - We store only an HMAC of each key, never the key itself, so we cannot show it again or recover it. If you lose it, create a new one and revoke the old one.
- Keep keys in environment variables or a secret manager, never in source code or client-side JavaScript.
Managing keys
Up to 5 active keys per account. Rotate by creating a new key, deploying it, then revoking the old one.
| Call | Does |
|---|---|
GET /v1/keys | Lists keys: id, prefix, name, created, last used, revoked. Never the secret. |
POST /v1/keys {"name": "prod"} | Creates a key (name optional, max 64 chars). Returns {"api_key": "ob_…", "note": …} once. |
DELETE /v1/keys/{id} | Revokes immediately. Returns {"revoked": "<id>"}. |
{"keys": [{"id": "2d5b7cc50a58190df95ea5383b283035", "prefix": "ob_7d3nmlvc_…", "name": "default",
"created_at": "2026-11-19T09:05:11.354609", "last_used_at": "2026-11-19T09:05:21.060757",
"revoked": false}]}
Rate limits
- Data endpoints are limited per key by plan: Free 60, Starter 300, Growth 600 requests a minute.
- Account endpoints (
/v1/usage,/v1/keys) have their own limit of 60 a minute, so you can check usage while rate-limited. - Responses carry
x-ratelimit-limit,x-ratelimit-remainingandx-ratelimit-reset; a429also carriesretry-after(seconds). - Keys are checked and rate limits applied before the request body is read.
- Sign-up is limited to 5 per hour per network.
Email verification
Sign-up sends a verification email. The Free plan works before you verify; verification is required before a paid plan can be enabled. The link calls POST /v1/verify with {"account_id", "token"} for you.
Auth errors
| Status | Body |
|---|---|
401 | {"detail": "invalid or missing x-api-key"}: missing, mistyped or revoked key |
403 | {"detail": "account suspended"} |
429 | {"detail": "rate limit exceeded"}, with retry-after |