---
title: "Agent Credentials"
description: "Scoped, revocable Postgres credentials and MCP tokens for AI agents. The agent never sees your real database credentials."
canonical: "https://pgbeam.com/docs/agent-credentials"
last-updated: "2026-10-29T19:01:20.000Z"
---

# Agent Credentials

> Scoped, revocable Postgres credentials and MCP tokens for AI agents. The agent never sees your real database credentials.

URL: https://pgbeam.com/docs/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](/docs/policies#human-and-passthrough-connections) for project default and per-database policies that cover your application's passthrough connections too.

## Create a credential

**CLI**

```bash
# 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…
```

**Dashboard**

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

**API**

```bash
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:

```bash
# 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](/docs/policies). |
| Status          | Active, revoked, or killed.                                             |

## 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](/docs/audit-log): 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](/docs/policies#test-a-policy-before-you-roll-it-out).

```bash title="Recommend a least-privilege policy for a credential"
pgbeam agents recommend-policy agt_xxx
```

## Revoke a credential

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

```bash title="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](/docs/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.

```bash title="Rotate in place"
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.

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

## Subagents need their own credential

A credential cannot be delegated. An agent holding one has no way to derive a narrower credential from it, and the MCP token cannot mint credentials either. Each credential is bound to exactly one policy profile, so passing it to a subagent gives the subagent everything the parent may do, under the parent's identity in the audit log, and revoking it stops both.

When an orchestrator runs subagents, issue each one its own credential from something that holds an [API key](/docs/api-keys) with the `agent:write` permission, and give it a policy no wider than its task:

```bash title="One credential per subagent"
pgbeam agents create --name orders-reader --policy pol_readonly_orders
```

That is a round trip to the control plane per subagent and one more credential to revoke when the subagent is done. In return, each subagent has its own audit trail, its own budget and its own kill-switch.

## 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](/docs/scram-auth) 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](/docs/policies): attach rules to a credential.
* [SCRAM-SHA-256 auth](/docs/scram-auth): how the password is verified.
* [Connection string](/docs/connection-string): connect a driver or ORM.
* [Hosted MCP](/docs/mcp): connect an MCP client.
* [Kill-switch](/docs/kill-switch): pause access instantly.