---
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-09-14T19:37:21.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 for project default and per-database policies that cover your application's passthrough connections too.

## Create a credential

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.

The response includes both front doors:

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

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

## Revoke a credential

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

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.

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.

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.

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