Storing keys in Settings is Preview (analytical-ledger#367). Keys that the host sets in the server environment keep working exactly as before.
What you can store
An active owner manages integration keys at Settings → Integrations. Inputs are write-only: a saved value, or even its last characters, never comes back to the browser.
| Name | Get it from | Used for |
|---|---|---|
ANTHROPIC_API_KEY | Anthropic Console | The Anthropic assistant lane, model discovery, receipt extraction and categorization. |
OPENAI_API_KEY | OpenAI API dashboard | The OpenAI assistant lane and model discovery. |
SIMPLEFIN_ACCESS_URL | SimpleFIN Bridge | Bank feed discovery, manual sync and scheduled sync. |
STRIPE_API_KEY | Stripe API keys | Read access to payouts and balance transactions. A restricted key is best. |
STRIPE_WEBHOOK_SECRET | Stripe webhooks | Verifying payout webhooks. |
TAX1099_API_KEY | Tax1099 | E-filing. The endpoint paths are placeholders; check the provider's contract before live filing. |
RESEND_API_KEY | Resend | Digest and statement-pack email. |
SLACK_WEBHOOK_URL | Slack incoming webhooks | Digest notifications. |
Some uses need more than the key. AI categorization also needs AI_CATEGORIZATION_PROVIDER=anthropic set by the host. Stripe webhooks need STRIPE_ENTITY_SLUG. Email needs a verified NOTIFY_EMAIL_FROM, and the digest needs NOTIFY_EMAIL_TO.
For SimpleFIN, exchange the Bridge's one-time setup token for the HTTPS access URL, and save that URL. See Import bank data.
Setting, replacing and clearing a key records the key's name, the owner and the time in integration_credential_event, in the same transaction as the change. No key material is ever written to that audit log.
Which value wins
A non-empty environment variable on the host always wins over a saved value. An empty one counts as unset.
- Saving a value that the host overrides still saves it. Clearing only deletes the stored value and cannot remove host configuration.
- To use the stored value, remove the environment override and restart the service.
- With no environment value, the instance decrypts the saved one. No saved value means unconfigured.
If a saved key seems ineffective, check for a host override first.
The encryption key
Saved values are encrypted with AES-256-GCM, using a fresh 96-bit IV on every save and the key's name bound in as authenticated data. The master key, LEDGER_CREDENTIALS_KEY, is 32 random bytes in base64. It is never stored in the database.
- Windows generates it once and keeps it in
secrets.jsonin your state folder. - Hosted instances have a generated-once key in their protected instance configuration.
- Source installs must provide one, generated once in your own secret manager, never in logs, chat, source control or a command argument.
Keep the key apart from your database backups, and restrict it to the application's service account. Whoever holds both can decrypt. If you lose it, stored credentials are unrecoverable: configure a replacement key and re-enter every credential. Environment values are unaffected.
A missing or malformed key disables stored credentials and saving, and Settings tells you why. A wrong key, altered ciphertext or an unsupported version marks the value unreadable, and anything that needs it fails closed. Restore the original key, or replace or clear the value.
There is no automatic key rotation or bulk re-encryption. Plan a maintenance window, keep the old key for restoring old backups, change the key through your secret manager, and re-enter the saved credentials. Every process that shares the database, including a separate assistant service, must receive the same key.
What saving does not do
Saving a key does not contact the provider, charge an account, send a message, claim a SimpleFIN setup token or file a return. There are no connection tests.
Normal integration actions keep their usual review and posting controls. A key lets a feature call out; it does not let anything post to the books without review.
Host-managed settings stay outside Settings: database access, authentication and sign-in credentials, cron and portal signing secrets, command-line login state, feature gates, entity mappings, notification recipients and provider base URLs.
Sending data to a provider is a choice you make by saving its key. Architecture overview lists what each integration sends.