Connectors

Referencing a credential you'll never see again

The connector screen that touches real secrets shows a vault key name, a fingerprint and a last-used time — and deliberately nothing that could ever be the value itself.

By The Kav team Published 3 min read

Of every screen in the Studio, this is the one where CLAUDE.md §12's secrets rule is most tempting to quietly break — a form asking someone to connect to a real municipal system practically invites a password field. It's built specifically to make that mistake awkward rather than easy.

What you type when you create an instance

Creating a connector instance asks for a vault key name — a string like connectors/rlz/umbraco/primary — never a credential value. There is no field on the form that would accept one. That's not an oversight to work around: a real secret typed into this form would land in the GraphQL request log, the durable outbox table, and the RabbitMQ payload carrying that mutation, all in one keystroke. The name is a pointer; the value it points to is created and rotated somewhere this screen never touches.

What the credentials panel shows, and the shape of what it refuses to show

Open an instance's credentials drawer and you get exactly three things: the vault key (a name), a fingerprint (a digest — enough to confirm which secret is bound, never enough to reconstruct it), and when it was last used. There is no reveal control anywhere on this screen, and no permission grant that unlocks one. That absence is the point: credential custody and capability authoring are built as separable roles, so the person wiring up a binding never needs the secret itself to do their job.

An empty fingerprint here — "not set" — is worth taking seriously the moment you see it, especially on an instance you're about to switch Active. It means the vault has nothing bound to this key yet, and going live in that state is exactly the failure the connector lifecycle's own pre-flight check exists to catch.

Where the actual secret lives

Per-tenant data-encryption keys are envelope-encrypted in Postgres, and the root key sits behind an unwrap-only interface — a file locally, AWS KMS in production. The Studio holds neither the root key nor the plaintext value at any point; it can point at a vault entry and later ask "is anything bound to this name," but it was never given a code path that could answer "what is it."

Rotation is a fingerprint change, not a value you'd ever compare by eye

When a credential is rotated behind the scenes, what you see on this screen is a new fingerprint and a fresh last-used timestamp — never a diff of the actual values, because there's nothing here capable of producing one. If two environments should be running the same credential and their fingerprints differ, that's your signal to go check, not a mismatch you resolve by pasting values into a comparison anywhere.

The fingerprint and last-used timestamp are exactly the two facts you need to answer "is this instance actually wired up, and is it being used" — reach for this drawer before assuming a connector is broken at the network level.