Authentication

Your server uses two separate credentials: an API key that authenticates log ingestion requests, and an encryption key that encrypts log content before it leaves your process. Both come from the Lumber mobile app. People signing in to the Lumber app use their own account, which is separate from both.

API Keys

API keys authenticate your server's log ingestion requests. Each key is scoped to a single app within your Lumber account. A key is a 32-character hexadecimal string.

How it works

The SDK sends each log as a POST /logs request to the Lumber API with:

Authorization: Bearer your_api_key

The API hashes the key with SHA-256 and looks up the hash. Only the hash is stored - the plaintext key is shown once, when you create it.

Creating a key

In the Lumber app, open your app and tap Secrets
Under API Keys, tap Add Key
Optionally give it a name, then tap Create
Copy the key immediately - it won't be shown again

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:

Create a new API key in the app
Update LUMBER_API_KEY in your environment
Deploy your updated config
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.

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. It is entirely separate from the API key, 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 shows it once on the Your Encryption Key screen. To copy it again later, open the app's Secrets screen on any of your devices that holds the key.

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 and AES-256-GCM. Lumber's servers store those wrapped copies but cannot decrypt them.

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 key from your plugin config. 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.