Encryption keys

The errorcore SDK encrypts every error payload inside your process, before it reaches the network. The key it uses is the project data encryption key, exposed to the process as ERRORCORE_DEK.

Format: 64 hexadecimal characters (32 bytes).

What the SDK does with it

Derives an AES-256-GCM encryption key with HKDF-SHA256 from the DEK.
Derives a MAC key the same way, unless an explicit ERRORCORE_MAC_KEY is configured.
Computes keyId as the first 8 bytes of sha256(derived encryption key), hex encoded. Both sides compute it from the DEK; it is never chosen independently.
Encrypts the payload and signs the envelope with an outer HMAC-SHA256 that the receiver verifies before attempting any decryption.

The DEK itself is never sent. Only the keyId travels on the envelope, so the receiver knows which key to unwrap.

Issue a key

Console → Settings → Encryption → Issue key, or the credentials step in Setup. It requires an organization admin and recent identity verification.

The backend generates the key with a CSPRNG, wraps it with the managed KMS, stores only the wrapped form, and returns the plaintext once. The console shows it once, behind an explicit acknowledgement.

Losing the plaintext means the payloads encrypted with it can no longer be produced by your servers; issue a new key and redeploy.

Statuses

Status	Meaning
`active`	Envelopes signed with this key are accepted.
`rotating`	Superseded by a newer key; still verifies until its overlap window ends.
`retired`	No longer verifies. New envelopes using it are rejected as unauthenticated.

Rotate

Rotation issues a new key and starts a bounded overlap window (at most 7 days) on the previous one. During the overlap both keys verify, so a rolling deploy never drops events. New envelopes should use the new key.

Sequence:

Rotate in the console and copy the new plaintext once.
Update ERRORCORE_DEK in your secret store.
Roll your servers.
Confirm in Admissions that recent events carry the new key id.

Retire

Retiring stops a key from verifying immediately. Envelopes still signed with it are rejected with an envelope-authentication failure and consume no quota. Payloads already stored under that key stay decryptable by the worker, so existing cases are unaffected.

Self-managed MAC keys

Setting ERRORCORE_MAC_KEY (or macKey) replaces the derived MAC key. Managed provisioning issues only a DEK, so an explicitly configured MAC key will not match a console-provisioned project key and its envelopes will fail verification. Use it only with a self-managed receiver.

What errorcore never does

It never logs the DEK, puts it in a URL, or exposes it to browser-readable config.
The console shows key ids and statuses only, never key material, after the one-time reveal.