Docs
Open Babbit

Guides

Give your code secrets and connect services

Your product needs keys and sign-ins to talk to other services. Babbit asks for them when the code needs them and makes sure no agent, transcript or log ever holds the value.

How Babbit asks for a secret

You don't set up secrets ahead of time. When a change's code declares a secret that Babbit doesn't hold yet, the change asks for it at a gate, before the work that needs it:

  • A key gate asks for a value, such as a payments API key. The gate links to the page of the service the key comes from.
  • A sign-in gate asks you to sign in to an account, such as a calendar or a customer's CRM, through OAuth. Babbit completes the sign-in through its own callback.

Babbit asks for prod's value and, once your project has launched, preprod's. Saving a value answers every gate waiting for it and retries any deploy that failed for lack of it.

Answer a key gate

  1. Open the change. The state card reads Needs you.
  2. On the Lines tab, find the key gate. It names the secret, such as STRIPE_API_KEY, and the tier.
  3. If you don't have a key yet, click the link to the provider's key page and create one.
  4. Paste the value into the gate's field and save it.

The field clears when you save, and the value is never shown again, to you or anyone else. The change continues on its own.

Connect an outside service

When a change needs to talk to an outside service, the Code Writing agent writes a connector: a small package that declares the hosts it calls and the key or sign-in it needs, tested against recorded answers rather than the live service. That declaration is what makes Babbit ask for the right secret, and what limits where the secret may be sent.

You don't write connectors yourself. Describe the outcome you want, such as Send a text message when an order ships, and the change asks for whatever the connector needs.

How handles work

No secret your code uses ever enters an agent's workspace. (The one exception is the model credential a Claude Code or Codex session needs; see Security guarantees.) Instead:

  1. When a command needs a secret, the agent asks the Babbit MCP for it by name. The MCP gives it a handle: an opaque string bound to that workspace, that tier and that name. The handle reveals nothing about the secret.
  2. The command puts the handle where the value would go, for example in an Authorization header.
  3. When the request leaves the workspace, Babbit's egress proxy swaps the handle for the real value, for that one request.
  4. The proxy scrubs the value out of the answer before the workspace sees it.

The proxy swaps a handle only for the workspace it was issued to, in the tier that workspace is bound to, and only when the request goes to a host the secret declares. If a handle goes to any other host, is written by hand, or is replayed from another workspace, the proxy refuses the whole request. GitHub and package registries never receive a secret.

Rules for every secret

RuleWhy
Write-only. A value goes in once and is never read back by a person or an agent.No screen, API or log can leak what it can't read.
One tier for anything that acts. A database URL, a deploy key or a payments key belongs to preprod or prod, never both.Preprod can never act with prod's credential.
Both tiers only for read-only keys. An API key that only reads, such as a model key, may answer preprod and prod.Reading is safe to share across tiers.
Hosts are declared. Each secret names the hosts it may be sent to.A key for your database can't be sent to a stranger's server.
Scrubbed everywhere. Every transcript, log and piece of evidence is scrubbed of live values before it's kept.A value that leaks into output reads as its name.

Organization and project secrets

A secret belongs to one of two scopes:

  • Organization: every project in the organization inherits it. Enter a shared key once.
  • Project: only this project uses it. A project secret with the same name as an organization secret overrides it, for the tiers it names.

Rotate a secret

Rotating stores a new version under the same name. The new version answers at once. Babbit lists who still holds the old version: each workspace until its next call, and each running service until it redeploys.

Babbit refuses to delete a secret while something still reads it and has no other value to fall back on.

Who may manage secrets

Writing a secret needs the Secrets permission, which only owners hold by default. Someone without it who tries is told to ask an owner. See Roles and permissions.