Consul ACL Token TTL: Unclear Renewal Policy for Long‑Running Services

Direct answer

Consul does not automatically renew ACL tokens, and it provides no pre-expiry notification, webhook, or renewal endpoint. Once a token passes its ExpirationTime, the server treats it as invalid and rejects protected requests. A long-running service cannot safely refresh its own token using only that token, because an expired credential cannot authenticate the renewal request. Rotation must be driven externally by a sidecar or controller that holds a separate management token with ACL token-read and token-write permissions.

Confirmed facts and likely explanation

Confirmed facts

• Consul enforces ACL expiration at request time; expired tokens are treated as revoked.
• Core Consul has no built-in automatic token-renewal mechanism.
• Token metadata fields such as ExpirationTime depend on the Consul version and edition.

Likely explanation

The uncertainty usually comes from conflating token use with token administration. Letting the expiring token create its successor would require ACL management privileges on that token, which is a privilege escalation and breaks least privilege.

Steps for this case

1. Deploy a rotation sidecar or controller with a dedicated management token scoped to ACL token read/write for the affected service policies.
2. Have the sidecar poll the target token metadata, compare ExpirationTime to current time, and issue a successor token with the same policies and service identities before a renewal threshold, such as 25 percent of the TTL remaining.
3. Write the new token atomically to the token file or secret store the service consumes. Reload the service only if it caches the token in memory.
4. After successful health checks with the new token, revoke the old token following a grace period.
5. Alert on rotation failures and keep a manually issued, longer-lived break-glass token for recovery.

Verification

Test in staging before changing production TTLs:

# Staging only. Read-only inspection of token metadata.
consul acl token read TOKEN_ID

1. Create a short-lived test ACL token, call a protected endpoint until expiry, and confirm requests are rejected with no automatic renewal.
2. Using a privileged token, read the test token metadata and confirm ExpirationTime is present in your Consul version.
3. Run the sidecar in staging with a short TTL and verify successor creation, atomic token replacement, service reload, and old-token revocation without an authentication gap.

Assumptions and uncertainty

This guidance assumes the service reads its token from a file or secret store rather than embedding it in code. Behavior is version- and edition-dependent; confirm ExpirationTime support and ACL endpoint availability for your installed Consul release before relying on this design.

Missing diagnostic detail

What Consul version and edition (OSS or Enterprise) are you running? This determines whether ExpirationTime and the required token-management endpoints exist, and it changes the rotation design.