q-ring 101 - secrets that expire (qring set --ttl)

गाइड

What it does

qring set KEY --ttl <seconds> gives a secret a lifetime. q-ring tracks how much of it has been used. At 75 percent the secret is marked stale and starts raising warnings. Once the lifetime runs out it is expired, and every read is refused. --expires does the same with a fixed ISO 8601 timestamp instead of a duration.

Try it

# A deploy token that lives for one hour
qring set DEPLOY_TOKEN --ttl 3600

# A certificate key with a fixed end date
qring set CERT_KEY --expires "2027-01-01T00:00:00Z"

# Watch the decay
qring list --show-decay
qring list --stale
qring health

# Scripts can ask before they run (expired counts as absent)
qring has DEPLOY_TOKEN --quiet || echo "token expired, fetch a new one"

Why it matters

Short-lived credentials are only short-lived if something enforces the end. A token that was meant for one deploy, then pasted into a file, works for as long as the issuer allows, which is often forever. With a TTL the end is enforced locally: an expired key cannot be read by your scripts, by qring exec, or by an agent over MCP, so a forgotten token stops being usable on this machine instead of waiting for an incident to surface it. qring health sorts every key into healthy, stale, expired, or no decay set, so rotation becomes a scheduled task.

Gotchas and good to know

• "Gone" means gone from reads. The keychain entry stays, marked expired, and each refused read is recorded in the audit log as blocked. Find the leftovers with qring list --expired and remove them with qring delete.
• Expiry is local. It does not revoke the token at the issuer. For credentials that matter, set the same lifetime at the provider, or rotate with qring rotate where the provider supports it.
• qring exec skips expired keys when it injects, so a job can fail on a missing variable rather than run with a dead token. That is the intended behavior.
• A project can cap lifetimes in policy: maxTtlSeconds under policy.secrets in .q-ring.json.
• For a value that should live in memory only, for a handful of reads, look at qring tunnel create with --ttl and --max-reads instead.

Go deeper

• Getting Started: health vs doctor
• Rotation and audit habits
• CLI reference