# 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.

Some 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.

> **WE KEEP YOUR KEYS SECURE:** 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

1. **You enter a key on the skill** — When 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.
2. **Secrets are encrypted before storage** — Bookbag 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.
3. **They're decrypted only to make the call** — At 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.
4. **Editing never reveals them** — Open 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) | — |

> **ANYTHING SENSITIVE IS A SECRET:** 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

1. **Open the skill** — On the agent's Skills tab, click the edit (pencil) on the installed skill.
2. **Paste the new key** — Enter the new value in the secret field and save. The old value is overwritten; everything else is untouched.
3. **Revoke the old one** — Revoke the previous token in the provider (Shopify, Stripe, …). Because keys are per-skill, rotation never disrupts another agent.

> **USE LEAST-PRIVILEGE TOKENS:** 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.

## What's next

- [Skills overview](/docs/skills/overview) — How skills become tools the model can call.
- [Shopify skills](/docs/skills/shopify) — Connect your store with an encrypted access token.
- [Bring your own API keys](/docs/agents/byo-keys) — Use your own model-provider keys, stored the same way.