Open the connection settings on most agent deployments and you find the same thing: one Postgres role, one password, pasted into an environment variable and shared by every agent run that ever touches the database. That single credential is a non-human identity in the loosest sense, but it is the wrong kind. It is anonymous, long-lived, and impossible to revoke without breaking everything that depends on it.
A real non-human identity for an agent reaching Postgres means a named, scoped principal whose every action is attributed back to a specific agent and authorization decision. This post walks through configuring that, with hoop.dev sitting inline on the Postgres connection as the place where identity is established and enforced.
Why a shared password is not a non-human identity
When an agent connects to Postgres with a shared role, the database sees one actor. Your audit log says app_user ran DELETE, not which agent invocation, under which task, approved by whom. You cannot scope access per agent because there is only one credential. You cannot revoke one agent without rotating the secret for all of them.
The fix is not a second shared password. It is an identity layer in front of Postgres that authenticates the agent as itself and attaches that identity to every statement on the wire.
Where hoop.dev sits
hoop.dev is an open-source Layer 7 access gateway. Its agent runs inside your network next to Postgres and speaks the native Postgres wire protocol. The AI agent connects to hoop.dev, not directly to the database. hoop.dev authenticates the caller through your identity provider, resolves a named non-human identity, then proxies the connection to Postgres using the credential configured on that connection. The database password never reaches the agent.
The point: the identity the agent presents and the credential that reaches Postgres are different things. hoop.dev attributes the named identity at the gateway, so the audit record carries who, not just what.
- Deploy the hoop.dev gateway and run the network-resident agent next to your Postgres instance. The agent opens an outbound connection to the gateway, so you expose no inbound port on the database.
- Register the Postgres connection with its host, port, database, user, password, and SSL mode. This credential lives on the connection and is hoop.dev's to use, not the agent's to hold.
- Define the non-human identity for the AI agent in your identity provider. hoop.dev consumes that identity over OIDC and reads group membership to drive authorization.
- Scope the identity to the connections and operations it needs. An ingestion agent might read two tables. A migration agent might write to one schema. Each is a distinct principal.
- Point the agent at the hoop.dev endpoint instead of the raw Postgres host. From the agent's side it is still a Postgres connection.
For the Postgres connection fields and identity setup, the getting started guide covers the gateway and agent install, and hoop.dev/learn explains how identity drives authorization across connections.
What a named non-human identity gives you
Once each agent is its own principal, three things become possible that a shared role never allowed. You can read an audit trail that names the agent behind every statement instead of a generic role. You can revoke one agent the instant it misbehaves without rotating a secret that a dozen other agents depend on. And you can scope two agents differently on the same database, because authorization is decided per identity at the gateway rather than baked into one credential everyone shares.
That is the practical payoff of treating an agent as an identity-aware principal: accountability, containment, and per-agent scope, all from the same connection.
Pitfalls
- Do not reuse one identity for every agent. The value of a non-human identity is lost the moment two agents share it. One principal per agent role.
- Do not grant the underlying Postgres role more than the broadest agent needs. The connection credential is a floor; scope the rest at the gateway.
- Watch standing access. An identity that can reach Postgres at all hours is a wider blast radius than one granted just in time. Pair non-human identity with short-lived grants where you can.
- Do not skip offboarding. An identity you provision but never plan to retire becomes a standing risk the day its agent is decommissioned.
FAQ
Does hoop.dev replace Postgres authentication?
No. Postgres still authenticates the connection credential. hoop.dev governs the connection in front of the database, adding the named non-human identity, authorization, and attribution on top.
Can the AI agent ever see the database password?
No. The credential is configured on the hoop.dev connection. The agent authenticates as its own identity and reaches Postgres through the proxy.
How is each query attributed?
hoop.dev records each session tied to the resolved identity, so the command-level log shows which agent ran which statement.
hoop.dev is open source. Read the architecture and self-host it from the hoop.dev repository on GitHub to see how non-human identity binds to a Postgres connection end to end.
