Agent Credentials

Scoped, revocable Postgres credentials and MCP tokens for AI agents. The agent never sees your real database 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…

Open your project, go to Agents, and select New agent. Pick a policy profile and copy the connection string and MCP URL from the result.

curl -X POST https://api.pgbeam.com/v1/projects/{projectId}/agents \
  -H "X-API-Key: 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

Field	Description
Postgres user	`agent_<id>`, used in the scoped connection string.
Postgres secret	Generated password. Shown once at creation.
MCP token	`pba_…` bearer token for the hosted MCP endpoint.
Policy profile	The rules enforced for this credential. See Policies.
Status	Active, revoked, or killed.

Revoke a credential

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

Revoke one credential

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.

Rotate in place

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

The same operation is available in the Agents 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.

Rotate, do not share

Issue one credential per agent. A per-agent credential gives you a clean audit trail and lets you revoke or kill a single agent without affecting the others.

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.

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.