Authorization error during restricted Role-bound API key access

Question

FaunaDB implements least-privilege access through Role documents that define specific permissions for collections and indexes. While short-lived session tokens issued via Identity support configurable TTLs, standard server, database, and collection-scoped API keys are persistent by default.
The current security model lacks a native mechanism to enforce automatic expiration or mandatory rotation policies for these long-lived API keys. If a key is bound to a Role with insufficient privileges for a specific query, the engine returns an authorization error, but the key itself remains valid until manually revoked or deleted by an operator.
Is there a method to set a maximum TTL for static API keys directly within the Fauna control plane? How does the system handle the graceful transition of credentials during a rotation to prevent request downtime without external orchestration logic?

Tasadduq Burney · Answer

Answer
No. Static Server, Database and Collection-scoped API keys cannot have a maximum TTL set in the Fauna control plane, and Fauna does not provide a built-in grace period or automatic overlap for rotating those keys. Authorization errors from a role-bound key are permission errors, not expiration errors; the key remains valid until you revoke or delete it.
Confirmed facts

Static API keys are persistent by default. The Dashboard and API for Server/Database/Collection keys do not expose a TTL or Expiration field.
Role-bound access is enforced per request. A key bound to a Role with insufficient privileges returns an authorization error while the key itself stays active.
Time-bound access is provided via Identity-based session tokens, which support configurable TTLs. Static keys do not.
Rotation of static keys is manual: create a new key, move clients to it, then delete the old key. There is no native overlap window.

Likely explanation for your error
The authorization error you are seeing is almost certainly a Role permission mismatch, not key expiry. The key is valid, but the Role attached to it does not grant read/write on the specific collection/index the query targets. This is consistent with role enforcement at request time.
Steps needed for this case

Verify the key type and Role. In the Fauna Dashboard open the key and note its Role. Check the Role document for collection and index privileges for the query path.
If you need time-limited access, do not use a static key. Issue short-lived Identity session tokens with a TTL for that workload.
If you must rotate a static key without downtime, orchestrate externally:

Create the replacement key with the same Role.
Deploy the new secret to clients via a secrets manager with a rollout window.
Only after confirming traffic uses the new key, delete the old key. Deletion invalidates all in-flight requests using it immediately.

Assumption: you are referring to Fauna v4 control plane behavior as of 2026-10-15. Behavior can change; verify in your tenant.
One diagnostic detail that changes the recommendation
Confirm whether the credential in use is a static Server/Database/Collection API key or an Identity session token. If it is an Identity token, TTL and refresh policies apply and the troubleshooting path is different.

Authorization error during restricted Role-bound API key access

1 answer

Answer

Confirmed facts

Likely explanation for your error

Steps needed for this case

One diagnostic detail that changes the recommendation

Your perspective belongs here.

0 question comments