A key's key_id names its rate-limit bucket (kid:<key_id>), its usage rows
(api_usage.key_id) and the admin views addressed by id. An id that changes
while the key stays the same splits all three.
A key whose configuration carries no key_id SHALL get a key_id derived from
the key's identity, so the same key has the same id on every load, every
restart and every replica that runs with the same key-lookup pepper. This
covers every key from AGENTFLOW_API_KEYS, and every key-file entry without a
key_id — including one in a key file the process cannot write the id back
to, as when the file is mounted read-only.
- GIVEN
AGENTFLOW_API_KEYS="k1:Support Agent"and a fixed key-lookup pepper - WHEN two separate
AuthManagerinstances load their keys - THEN both give the key the same
key_id, of the formdefault-support-agent-<8 lowercase hex>
- GIVEN a loaded environment-configured key
- WHEN the manager reloads
- THEN the key's
key_idis unchanged, and so is its rate-limit bucket
- GIVEN
AGENTFLOW_API_KEYS="k1:bot,k2:bot" - WHEN the manager loads its keys
- THEN the two keys have different
key_idvalues
- GIVEN a key file the process cannot write, holding an entry that has a
key_lookupand nokey_id - WHEN two separate
AuthManagerinstances load it, and one of them reloads - THEN the entry has the same
key_idin both managers and after the reload
- GIVEN a writable key file holding an entry that has a plaintext
keyand nokey_id - WHEN the manager loads it
- THEN the file on disk now carries the
key_idthe manager uses, and it is the id derived from that key
The derived id SHALL come from the peppered key-lookup digest — the entry's
stored key_lookup, or compute_key_lookup over its plaintext key — never
from the plaintext key or an unpeppered hash of it: the id is written to logs,
Redis key names, usage rows and admin responses, and must not let a guessed
key be confirmed offline. An entry that has neither a plaintext key nor a
key_lookup (a legacy hash-only entry) has nothing to derive from and keeps a
random id.
- GIVEN an environment key
k1and key-lookup pepperP - WHEN the manager loads it
- THEN the
key_idsuffix equals the first 8 characters ofcompute_key_lookup("k1", P)
- GIVEN a key-file entry with
key_lookup: Land nokey_id - WHEN the manager loads it
- THEN the
key_idsuffix equals the first 8 characters ofL
- GIVEN the same environment key and two different key-lookup peppers
- WHEN one manager loads it under each pepper
- THEN the two
key_idvalues differ