FaunaDB RBAC and External Identity Providers: Secret Key Rotation Logic

Direct Answers

Recommended pattern: Create a dedicated FaunaDB key for each external session, persist the key's id (not the secret) in your session store alongside the external session identifier, and run a scheduled job that calls the Admin API DELETE /keys/{key_id} when the external session expires or is revoked.

Bulk revocation: FaunaDB's Admin API does not expose a single bulk-delete endpoint for keys. You must iterate the list of key IDs you want to revoke and issue individual delete requests, or use a client library that batches the underlying HTTP calls.

Why This Pattern

FaunaDB keys have no native TTL or expiration field. The only revocation mechanism is the Admin API delete operation, which requires the key's internal id. Because keys are immutable once created, rotating credentials means creating a new key and deleting the old one.

Mapping each external session to its own FaunaDB key keeps the blast radius small: if a session is compromised, only that one key needs revocation. Storing the key id (not the secret) in your session store lets you revoke without ever handling the secret again.

Implementation Steps

1. When an external identity provider issues a session, call POST /keys with a role that grants the minimal privileges needed for that session. Capture the returned id and secret.
2. Store the id in your session store keyed by the external session ID. Deliver only the secret to the client (or exchange it for a short-lived token in your own layer).
3. When the external session ends (logout, timeout, IdP revocation), retrieve the FaunaDB key id and call DELETE /keys/{key_id}.
4. Run a periodic reconciliation job that lists all keys (GET /keys), cross-references with your session store, and deletes any keys whose external session no longer exists.

Efficiency Considerations

• Assign a common role (e.g., external-session) to all short-lived keys so the reconciliation job can filter with ?role=external-session.
• If you need to revoke all keys for a specific user or tenant, maintain a mapping from user/tenant to key IDs in your own store; FaunaDB does not index keys by custom metadata.
• Batch deletions in your orchestration layer to stay within FaunaDB rate limits (typically 100 requests/second for Admin API).

Risks and Mitigations

• Orphaned keys: If the revocation job fails, keys remain valid. Make the job idempotent (delete ignores missing keys) and alert on reconciliation mismatches.
• Rate limits: High session churn can hit Admin API limits. Consider reusing a key for the lifetime of an external access token if your threat model allows, or implement a token-exchange layer that issues short-lived JWTs backed by a longer-lived FaunaDB key.

Verification

# List keys for a role
curl -H "Authorization: Bearer $ADMIN_KEY" \
  "https://db.fauna.com/admin/keys?role=external-session"

# Delete a specific key
curl -X DELETE -H "Authorization: Bearer $ADMIN_KEY" \
  "https://db.fauna.com/admin/keys/$KEY_ID"

# Confirm deletion
curl -H "Authorization: Bearer $ADMIN_KEY" \
  "https://db.fauna.com/admin/keys/$KEY_ID"
# Expect 404

One Diagnostic Detail

What is the expected peak sessions-per-minute? This determines whether per-session keys are viable or if you need a token-exchange layer to reduce Admin API write volume.