Credentials & security
How Bookbag stores the API keys your skills use: encrypted at rest with AES-256-GCM, scoped to a single agent, and never shown back. Enter a key once on the skill; rotate it any time.
View as MarkdownSome skills call services that need authentication — your Shopify store, a Stripe account, a Slack workspace, your own API. Bookbag keeps those keys on the skill itself: you enter them once when you add the skill, and they power that skill for this agent. There is no separate place to manage them and no key sitting in a config file.
Every secret you enter — access tokens, API keys, secret keys, webhook URLs — is encrypted at rest with AES-256-GCM before it touches the database, and is never shown back to you in the UI or the API. Only the running skill can decrypt a key, in memory, at the moment it makes the call.
How it works
- 1You enter a key on the skillWhen you add or edit a skill that needs auth, its credential fields appear right in the dialog (derived from what that connector requires). You type the key there — not on a shared settings page.
- 2Secrets are encrypted before storageBookbag splits the values: identifiers that aren't sensitive (your shop domain, a help-desk subdomain, an account email, a channel name) are stored as-is so you can see and edit them; true secrets (tokens, keys, webhook URLs) are encrypted with AES-256-GCM and written as an opaque blob.
- 3They're decrypted only to make the callAt the moment the skill runs, Bookbag decrypts the secret in memory, passes it to the connector for that single request, and discards it. The plaintext is never logged and never returned to the client.
- 4Editing never reveals themOpen a skill to change its settings and the secret fields are blank with “leave blank to keep”. Type a new value only when you want to rotate the key; otherwise the saved one is kept untouched.
What's encrypted vs. stored plainly
| Stored encrypted (never shown back) | Stored plainly (visible & editable) |
|---|---|
| Access tokens, API keys, API tokens, secret keys | Shop domain (e.g. your-store.myshopify.com) |
| Slack bot tokens & incoming webhook URLs | Help-desk subdomain, account email |
| Stripe secret keys, Tavily web-search keys | Slack default channel, mailbox / org IDs, instance URL |
| Custom-skill request headers (they usually carry a key) | — |
Bookbag classifies a field as a secret whenever its name looks like a token, key, secret, password, or webhook URL — so new connectors are protected by default, not by a hand-maintained list.
Scope & isolation
- Credentials are scoped to one agent — a key you add to one agent is never visible to or usable by another agent or workspace.
- Each skill carries its own credentials. Removing a skill removes its keys; reinstalling asks for them again.
- The encryption key lives on the server (an
OPENCHAT_ENCRYPTION_KEY), separate from the database. A database copy alone cannot reveal your secrets.
Rotating a key
- 1Open the skillOn the agent's Skills tab, click the edit (pencil) on the installed skill.
- 2Paste the new keyEnter the new value in the secret field and save. The old value is overwritten; everything else is untouched.
- 3Revoke the old oneRevoke the previous token in the provider (Shopify, Stripe, …). Because keys are per-skill, rotation never disrupts another agent.
Give each skill the narrowest scope it needs — a read-only Shopify token for order lookups, a restricted Stripe key for billing reads. If a token is ever rotated out, the blast radius stays small.