Agent Credentials

An agent credential is a PgBeam-issued identity for one agent. It comes with a scoped Postgres username and password and an API token for the hosted MCP endpoint. PgBeam authenticates the credential itself and connects upstream with your stored database credentials, so the agent never sees your real ones. Every credential is scoped to a policy, revocable, and kill-switchable on its own.

The same credential model issues identities for people, not just agents. Every credential carries a principal_type of agent or human. A human credential gives an analyst or contractor a scoped, masked, audited connection with the exact same guardrails an agent gets. Throughout these docs, "agent credential" is the common case; the mechanics are identical for human credentials. See Policies for project default and per-database policies that cover your application's passthrough connections too.

Create a credential

# Create a policy first (once), then pass its pol_… id to --policy:
pgbeam policies create --name read-only --mode read_only
pgbeam agents create --name analytics-bot --policy pol_1a2b3c…

curl -X POST https://api.pgbeam.com/v1/projects/{projectId}/agents \
  -H "Authorization: Bearer pbo_..." \
  -d '{"name": "analytics-bot", "policy_profile_id": "pol_1a2b3c…"}'

The response includes both front doors:

# Scoped Postgres connection string
postgresql://agent_4f2c:****@a1b2c3.proxy.pgbeam.app:5432/app

# Hosted MCP endpoint (token-scoped: the same URL for every credential)
https://<project>.proxy.pgbeam.app/mcp   # Authorization: Bearer pba_…

What a credential carries

Right-size its policy from traffic

Once a credential has run for a while, PgBeam can derive the tightest policy that would still pass everything it has legitimately run, from its audit history: the exact tables it touched, the statement kinds it used, read-only when it never wrote, and a max_rows ceiling from its observed result sizes. The candidate is proven safe by replaying it against that same history and is advisory only. It loads into the policy editor for review and never changes anything until you save. See Right-size from traffic.

pgbeam agents recommend-policy agt_xxx

Revoke a credential

Revocation is immediate. The next statement on that credential is refused.

pgbeam agents revoke agt_xxx   # the agt_… id from `pgbeam agents list`

To stop an agent without deleting it, use the kill-switch. The kill-switch pauses access with no credential rotation; revocation removes the credential entirely.

Rotate a credential

Rotation issues a fresh Postgres password and MCP token for the credential in place: the id, username, name, policy, and audit history stay the same. Connections using the old password are dropped within seconds, so update your agent before its next call. The new secrets are shown once.

pgbeam agents rotate agt_xxx   # the agt_… id from `pgbeam agents list`

The same operation is available in the Credentials tab (the rotate action on a credential) and over the API as POST /v1/projects/{project_id}/agents/{agent_id}/rotate.

Need zero overlap instead? Issue a second credential, cut the agent over, then revoke the first. Rotation in place is simpler, but two credentials let you verify the new one before retiring the old.

Authentication model

PgBeam terminates authentication itself. The credential's password is verified against the credential, not passed through to your database. Authentication uses SCRAM-SHA-256 by default, so the password never crosses the wire, with cleartext-over-TLS available as a fallback for clients that cannot do SCRAM. TLS is mandatory either way.

Related

• Policies: attach rules to a credential.
• SCRAM-SHA-256 auth: how the password is verified.
• Connection string: connect a driver or ORM.
• Hosted MCP: connect an MCP client.
• Kill-switch: pause access instantly.