enTrail

Box

Key lifecycle Beta

A key lets one system write into one environment. It is a credential for a machine rather than for a person, and the whole lifecycle is built so you can replace one without a window where nothing can send.

What a key is

PartNotes
access idNames the key, looks like acc_…, and is not secret. It appears in logs and in the console.
secretProves it. Shown once, at creation. Only a hash is stored, so it cannot be shown again.
slotPrimary or secondary. Two slots per environment is what makes rotation seamless.
environmentA key belongs to exactly one. A development key cannot write into the production chain.

Three rules the database enforces

These are not conventions or screen validation. They hold whatever the console does.

Issuing

  1. Open the project, then the environment, then Keys.
  2. Create a key in a free slot and name it for the system that will use it.
  3. Copy the secret now. It is shown once. If you lose it, revoke that key and issue another; there is no recovery path, by design.
  4. Put it where that system reads secrets. Not in the repository, not on a command line, not in a URL.
x-entrail-access-id: acc_1f3a9c2b
x-entrail-secret:    <the secret>

Rotating without downtime

This is why there are two slots. Both keys are valid at once, so nothing has to change in lockstep and no deployment has to be timed.

  1. Issue a new key into the free slot. Both now work.
  2. Move your senders one deployment at a time. Watch the live view until nothing is arriving on the old key.
  3. Revoke the old key, then promote the secondary into the free primary slot. Anything still using the old key gets 403 key_revoked within seconds, which is how you find the sender nobody remembered. Anything accepted in the moment before that lands is quarantined at sealing and shown under Refused, so a revoked key can never put a record in your chain.

Do this on a schedule you choose, and always when someone who could have copied the secret leaves. A key outlives the person who took it unless you do something about it.

The step people skip

Between moving your senders and revoking, actually confirm the old key is idle. Revoking while something still uses it damages nothing sealed, but it does turn a planned rotation into an incident during business hours. The trail explorer, filtered by key, is the check — the live view has no key filter.

If a secret leaks

Revoke first, then issue a replacement and move senders onto it. Do not wait for a tidy window.

Then be precise about what happened, because the honest answer is narrower than instinct suggests. A leaked key can write events into that one environment, which pollutes your trail with records you did not author. It cannot alter, delete or reorder anything already sealed, it cannot reach another environment, and it cannot make the chain lie.

Every event it wrote stays in the record, in order, exactly as provable as everything else. Note when the key was issued and when it was revoked: events between those two points are identifiable, and an auditor can be shown precisely that window rather than asked to take your word about the rest.

Who can do this

Box admins and developers both manage keys: issue, disable, enable, revoke and promote. A box auditor never sees a key at all. Those roles are in access to a box.

Practical checklist

Every one of these acts is sealed into the box's own trail. When a key came into existence, when it was revoked, and by whom, are themselves records nobody can edit afterwards. That is what makes the leak story above defensible rather than merely plausible.