enTrail

Box

Key lifecycle Built

A key lets one system write into one environment. It is a credential for a machine, not for a person, and the whole lifecycle is built so you can replace one without a gap 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. We store only a hash, so we cannot show it to you again.
slotprimary or secondary. Two live slots per environment is what makes rotation seamless.
environmentA key belongs to exactly one. A development key cannot write into the production chain.

Issuing a key

  1. Open the project, then the environment, then Keys.
  2. Create a key in a free slot and give it a name that says which system will use it.
  3. Copy the secret now. It is displayed once. If you lose it, disable 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 in a command line, not in a URL.

Issuing a key is recorded on the box's own trail, so the question of when a credential came into existence has an answer nobody can edit.

Rotating without downtime

This is why there are two slots. Both keys are valid at the same time, so nothing has to be changed in lockstep.

  1. Issue a new key into the free slot. Both now work.
  2. Move your senders to the new access id and secret, one deployment at a time. Watch the live view until nothing is arriving on the old key.
  3. Disable the old key. Anything still using it starts getting 401 immediately, which is how you discover the sender nobody remembered.

Rotate on a schedule you choose, and always when someone with access to the secret leaves. A key outlives the person who copied it unless you do something about it.

If a secret leaks

Do not wait for a tidy rotation. Disable the leaked key first, then issue a replacement and move senders onto it.

Be clear about what a leaked key can and cannot do. It can write events into that environment, which pollutes your trail with records you did not author. It cannot alter or delete anything already sealed, and it cannot make the chain lie: every event it wrote stays in the record, in order, and is exactly as provable as anything else. Tell an auditor when the key was disabled, and the events between those two points are identifiable.

Disabling

Disabling stops the key from authenticating, at once. It does not touch the events that key already sent, and it never could: sealed evidence is not editable by anyone holding a credential, which is the point of the product.

Who can do any of this

Issuing, rotating and disabling keys is a box admin action. A developer sees the connect details for their work, and a box auditor cannot change keys at all. Those roles are described in access to a box.

Practical checklist