API Key Rotation Guide

Why Rotate Keys

• Reduce risk window — Shorter key lifespan limits exposure if compromised
• Compliance requirements — Many security frameworks require periodic credential rotation
• Personnel changes — Rotate when team members with key access leave
• Principle of least privilege — Opportunity to review and tighten permissions

Rotation Process (5 Steps)

1. Create new key with same permissions — Developer Portal → API Keys → Create. Match the permission set of the existing key.
2. Update integration config — Deploy the new key to your application's environment variables or secrets manager.
3. Verify new key works — Test with GET /api/enterprise/v1/ping to confirm authentication succeeds.
4. Monitor for errors on old key — Wait 1-24 hours, check audit logs for requests still using the old key.
5. Revoke old key — Once no traffic uses the old key, revoke it permanently.

Zero-Downtime Rotation

For systems that cannot tolerate any downtime during rotation:

1. Create the new key (both keys are now active simultaneously)
2. Configure your app to support both keys (try new key, fall back to old)
3. Deploy the update — traffic seamlessly shifts to the new key
4. Remove fallback logic after confirming new key is working
5. Revoke the old key

Automated Rotation (Python Example)

import os, requests, time

PORTAL_API = "https://api.genuinein.com/api/enterprise/v1"
ADMIN_KEY = os.environ["GENUINEIN_ADMIN_KEY"]

def rotate_key(old_key_id):
    headers = {"X-API-Key": ADMIN_KEY}

    # 1. Create new key with same permissions
    resp = requests.post(f"{PORTAL_API}/developer/keys", headers=headers, json={
        "name": f"production-key-{int(time.time())}",
        "permissions": {"talent": {"search": True, "read": True, "pool": True}}
    })
    new_key = resp.json()["data"]["api_key"]  # Only shown once!
    new_key_id = resp.json()["data"]["key_id"]

    # 2. Update config (e.g., AWS Secrets Manager)
    update_secrets_manager("GENUINEIN_API_KEY", new_key)

    # 3. Verify new key works
    verify = requests.get(f"{PORTAL_API}/ping",
        headers={"X-API-Key": new_key})
    assert verify.status_code == 200

    # 4. Wait for traffic to shift
    time.sleep(300)  # 5 minutes

    # 5. Revoke old key
    requests.delete(f"{PORTAL_API}/developer/keys/{old_key_id}",
        headers={"X-API-Key": ADMIN_KEY})

    print(f"Rotation complete. New key ID: {new_key_id}")

Rotation Schedule

Emergency Rotation

If a key is suspected or confirmed compromised:

1. Revoke immediately — Don't wait for a replacement. Revoke the compromised key now.
2. Create new key — Generate a fresh key with appropriate permissions.
3. Deploy new key — Update all integrations using the compromised key.
4. Review audit logs — Check for unauthorized access during the exposure window.
5. Report incident — Document the compromise timeline and actions taken.