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
| Part | Notes |
|---|---|
| access id | Names the key, looks like acc_…, and is not secret. It appears in logs and in the console. |
| secret | Proves it. Shown once, at creation. Only a hash is stored, so it cannot be shown again. |
| slot | Primary or secondary. Two slots per environment is what makes rotation seamless. |
| environment | A 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.
- One live key per slot. Not one key per slot for ever: a revoked key releases its slot, so a mistake made once does not cost you that slot permanently.
- Revocation is final. There is no unrevoke — not for you, not for us, not for any role. A key you revoked is gone, which is what makes revoking it a real answer to a leak rather than a pause.
- No live key on a closed environment. Closing revokes first, so nothing can still be writing to something you believe is shut.
Issuing
- Open the project, then the environment, then Keys.
- Create a key in a free slot and name it for the system that will use it.
- 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.
- 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.
- Issue a new key into the free slot. Both now work.
- Move your senders one deployment at a time. Watch the live view until nothing is arriving on the old key.
- Revoke the old key, then promote the secondary into the free primary slot. Anything still using the old key gets
403 key_revokedwithin 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
- One key per sending system, never one shared key, so you can revoke narrowly
- Secrets from a secret store or an environment variable, never from the repository
- Rotate when someone leaves, and disable their platform account in the same pass
- Confirm the old key is idle before revoking it
- Separate keys for development and production, which the environment split already enforces