Key Revocation & Rotation

Revocation takes effect in under 5 minutes

If your API key leaks (committed to Git, exposed in logs, stolen in a breach), you can revoke it instantly from the dashboard.

Timeline:

Click "Revoke" in dashboard
0 seconds
Database updated
~100ms
Redis cache invalidated
~500ms
Workers cache expires
~5 minutes (TTL)
Key fully revoked
~5 minutes ✅

Why not instant? We cache API keys in Redis (5min TTL) for performance. Without caching, every request would hit the database (20-50ms), making the API slower.

Tradeoff: 99.9% of requests are cached (fast), but revocation takes up to 5 minutes to propagate fully.

How to revoke a key

Method 1: Dashboard (recommended)
  1. Go to /dashboard/api-keys
  2. Find the key you want to revoke
  3. Click the 🗑️ icon or "Revoke" button
  4. Confirm (no undo!)
  5. Key is immediately marked as revoked in database
Method 2: API (for automation)
DELETE /api/v1/keys/:keyId
Headers:
  X-API-Key: YOUR_MASTER_KEY
  X-API-Secret: YOUR_MASTER_SECRET
  X-Signature: ...
  X-Timestamp: ...

Response:
{
  "success": true,
  "message": "API key revoked",
  "keyId": "key_abc123",
  "revokedAt": "2024-01-08T10:30:00Z",
  "cacheExpiry": "~5 minutes"
}

What happens after revocation

Immediately (0-1 minute):
  • New requests with this key start failing (cache miss → DB lookup → revoked)
  • Dashboard shows key as "Revoked" with red indicator
After 5 minutes (cache TTL):
  • All requests with this key fail (100% blocked)
  • Error: 401: API key revoked
Permanent:
  • Key cannot be un-revoked (create a new one)
  • Key stays in database for audit trail
  • Old request logs still reference this key ID

Key rotation (recommended every 90 days)

Why rotate? Even if your key hasn't leaked, rotating regularly limits damage if it does leak later.

Rotation process (zero downtime):

Step 1: Create new key
Dashboard → API Keys → "Create New Key"
Copy new key and secret (shown only once!)
Step 2: Deploy new key to production
Update environment variables:
OBITOX_API_KEY=ox_new...
OBITOX_API_SECRET=sk_new...
Restart/redeploy your application
Step 3: Verify new key works
Make a test request, check logs/monitoring
Confirm no errors
Step 4: Wait 24 hours (optional but recommended)
Keep old key active for 1 day
Catches any services still using old key
Check logs for requests with old key
Step 5: Revoke old key
Dashboard → Find old key → Revoke
Old key stops working within 5 minutes
If anything breaks, you know what service still needs updating

Automatic rotation reminders

We'll email you:

  • 7 days before 90-day mark: "Consider rotating your API keys soon"
  • At 90 days: "Your API keys are 90 days old (security best practice: rotate)"
  • At 180 days: "Your API keys are 6 months old (strongly recommend rotating)"

We don't force rotation (your keys will keep working), but we'll nag you because it's good security hygiene.

Emergency revocation (compromised key)

Scenario: You discover your API key was committed to a public GitHub repo 2 weeks ago.

1. Revoke immediately (do this first!)
Don't wait. Don't investigate. Revoke now.
Dashboard → API Keys → Revoke
Takes effect in 5 minutes
2. Create new key
Generate fresh key + secret
Update environment variables
Deploy to production ASAP
3. Check logs (optional)
Dashboard → API Keys → View old key → Request logs
Look for suspicious IPs, unusual usage patterns
Email support@obitox.com if you see abuse
4. Remove from Git history
git filter-branch or BFG Repo-Cleaner
Force push to rewrite history
Even though key is revoked, clean up the leak

What we do on our side

When you revoke a key:

  • Mark key as revoked in database (immediate)
  • Delete from Redis cache (500ms)
  • Set TTL to 0 on Workers cache (forces refresh)
  • Log revocation event (audit trail)
  • Email you confirmation ("Key ox_196a... revoked")

We do NOT:

  • Delete the key from database (kept for audit trail)
  • Notify you of every failed request (would be spam)
  • Automatically create a new key (you control this)

Best practices (actually follow these)

⚠️ Rotate keys every 90 days
Set a calendar reminder. We'll email you, but don't rely on that.
Takes 10 minutes, prevents months of potential exposure if leaked.
⚠️ Use separate keys per environment
Dev: ox_test_...
Staging: ox_staging_...
Production: ox_live_...
If dev key leaks, prod is safe.
⚠️ Never hardcode keys in source code
❌ const API_KEY = "ox_196aed8..."; // NEVER DO THIS
✅ const API_KEY = process.env.OBITOX_API_KEY;
⚠️ Add .env to .gitignore
Most common leak: .env file committed to Git.
Check .gitignore includes .env*
⚠️ Limit key scope (future feature)
Coming soon: Create keys with limited permissions (read-only, specific providers, IP restrictions).
For now: Create separate keys for different services, revoke individually if needed.
⚠️ Monitor key usage
Dashboard → API Keys → Click key → View usage
Unexpected spikes? Revoke and investigate.

FAQ

Can I un-revoke a key?
No. Revocation is permanent. Create a new key instead.
Why: Simpler logic, prevents accidents (can't un-revoke compromised key by mistake).
How many keys can I have?
Free: 5 active keys
Pro: 20 active keys
Enterprise: Unlimited
Revoked keys don't count toward limit.
What if I lose my secret?
We show it only once when you create the key. If you lose it:
1. Revoke the old key
2. Create a new key
3. Save the secret this time (use a password manager)
Can I rename keys?
Yes. Dashboard → API Keys → Click key → Edit name
Name is for your reference only (not used in API calls).
Do revoked keys show in logs?
Yes. Old requests still reference the key ID.
Dashboard shows "(Revoked)" badge next to key name in logs.
← Previous
Rate limits & abuse
Next →
Failure modes