API Keys

Your server uses one credential, an API key, which carries two things: a token that authenticates log ingestion requests, and the app's encryption key, which encrypts log content before it leaves your process. It comes from the Lumber app. People signing in to the Lumber app use their own account, which is separate from it.

The key

API keys authenticate your server's log ingestion requests and carry the app's encryption key. Each key is scoped to a single app within your Lumber account. A key is two values joined by a dot: a 32-character hexadecimal token, then the app's base64-encoded encryption key.

<token>.<encryptionKey>

How it works

The SDK splits the key at the dot. It encrypts each log with the encryption key, which never leaves your process, and sends it as a POST /logs request to the Lumber API with only the token:

Authorization: Bearer <token>

The API hashes the token with SHA-256 and looks up the hash. Only the hash is stored, so the key is shown once, when you create it. If you call the API yourself, send only the part before the dot.

Creating a key

Creating an app takes you straight to adding its first key. To add another:

  1. In the Lumber app, open your app, tap the gear, and tap Secrets
  2. Under API Keys, tap Add Key
  3. Optionally give it a name, then tap Create
  4. Tap Copy & Close. The key won't be shown again

Adding a key needs the app's encryption key on that device, since every key carries it. Each plan allows a set number of API keys per app (one on Hobby). See pricing.

Rotating keys

If your plan allows more than one key per app, create a new key before deleting the old one to avoid downtime:

  1. Create a new API key in the app
  2. Update LUMBER_API_KEY in your environment
  3. Deploy your updated config
  4. Delete the old key in the app

Deleting a key takes effect immediately: requests that still use it get a 401 response. On Hobby, which allows one key per app, delete the old key first and then create the new one.

Rotating replaces the token. The new key carries the same encryption key as the old one, since each app has one (see Key rotation).

Multiple keys

On plans with more than one key per app, you can use separate keys for each environment (staging vs. production) or revoke access for a specific deployment without affecting others.

Encryption Key

The encryption key is a 32-byte symmetric key, base64-encoded, used for AES-256-GCM encryption (authenticated encryption, one of the ciphers HTTPS uses). It's the part of each API key after the dot, and the SDK never sends it to the Lumber API.

Where it comes from

When you create an app, the Lumber app generates its encryption key on your device, and every API key you create for the app carries it.

The Lumber app keeps the key in your device's secure storage. It only leaves the device wrapped (encrypted) to the account key of a user who has access to the app, using X25519 key agreement (the key exchange behind Signal and TLS 1.3) and AES-256-GCM. Lumber's servers store those wrapped copies but cannot decrypt them.

Sharing with your team

Apps can be shared with the members of your team, or with guests you invite to a single app. Your plan's seat count limits how many members your team can have and how many guests each app can have.

There's nothing to copy and paste. Whenever someone who already has an app's key opens Lumber, their device wraps the key to the account key of each person with access who doesn't have it yet. Those people's devices then unlock the app automatically the next time they open Lumber.

Pasting a key

If a device doesn't have an app's key yet, the app shows a Paste Key option. Open the app's Secrets screen, tap Paste Key, and paste the API key from your plugin config (or the encryption key on its own). Lumber checks the key against the app's existing logs before saving it, then uploads a copy wrapped to your account key so your other devices get it too.

Key rotation

Each app has a single encryption key, and the SDK marks every log with keyVersion: 1. Rotating an app's encryption key isn't supported yet: logs encrypted with one key can't be read with another.

Losing the key

If nobody with access to an app still has its key on a device, and no plugin config still has one of its API keys, the app's logs can't be decrypted. Lumber can't recover the key for you.

← PreviousAI AgentsNext →Encryption