How Neon made Postgres claimable for agents with auth.md

Neon used auth.md to keep a familiar agent workflow from stalling. When an agent needs a database but no person is available to create an account, Claimable Neon lets it provision a bounded temporary Postgres project, keep building, and hand ownership to a person later.

Most signup paths still assume a person can open a browser, verify an email address, approve access, or copy an API key. We published auth.md in May to give agents a discoverable registration path, including an anonymous start when the service permits it.

An agent can reach a temporary database project before anyone signs up, within the limits Neon sets for the unclaimed project.

Registration should be discoverable

A service publishes a Markdown file on its own domain. The file describes the registration flows and scopes the service supports and points the agent to standard OAuth metadata and endpoints. Any service can publish it, and any agent can read it.

Our launch post explains the protocol and its registration flows. The first-week recap covers the first services and builders that adopted it. Our implementation walkthrough shows how an API can register an agent anonymously, let it work with restricted access, and later bind that registration to a person.

Cloudflare and Firecrawl worked with us on the launch demo, where an agent used ID-JAGs to register with both services and obtain credentials.

Now there is a database implementation to study. Neon used auth.md to build Claimable Neon. An agent can provision a temporary Neon project, keep building, and offer the result to a person later. If the person wants it, they claim it into a Neon organization. If not, it expires.

The auth.md method Neon chose

Our launch post grouped auth.md into two user-level flows: agent verified and user claimed, with email-required and anonymous starts inside the user-claimed flow. The current reference implementation makes the API-level choice more precise. It advertises three registration methods in the identity_types_supported field, and the request schema accepts the same three bodies:

1. identity_assertion: the agent presents an ID-JAG tied to a user identity.
2. service_auth: the agent knows the user's email but has no provider assertion, so a claim ceremony is required before credentials are issued.
3. anonymous: the agent has no user identity, so the service can issue restricted pre-claim access and defer the claim ceremony.

Claimable Neon uses the anonymous method. The agent does not pretend to be a person or inherit a person's Neon API key. Neon creates a limited temporary project and controls its capabilities, expiration, credentials, and transfer.

A database makes the boundary concrete. The agent needs real credentials and enough control to build an application, while Neon has to constrain what an unknown agent can create and consume. Ownership also has to move cleanly when a person arrives.

The agent discovers when to use it

An agent can find Claimable Neon through Neon llms.txt, which points to the Neon auth.md file. Before creating anything, the agent checks whether it already has access to a Neon account. If NEON_API_KEY is set or the Neon CLI has an authenticated account profile, it uses that account. Claimable Neon is for the earlier moment when the application needs a database and no Neon account is available.

This does not give every agent a route around normal account controls. It tells the agent which registration path applies, then leaves Neon to enforce that path.

Neon provisions one bounded project

Registration returns one decision per requested capability, so the agent has to read what it was actually granted instead of assuming.

A documented CLI path that requests the Data API and Managed Better Auth is:

neon claim create --service data-api --service auth --env-pull

The command registers an anonymous identity, provisions one temporary project, requests the optional services, and writes the granted connection values to the application's environment file. Postgres is included. The Data API and Managed Better Auth are available when requested and granted. A neon.ts configuration file can declare the same services, while the flags provide a supported CLI-only path.

The registration response includes one decision for each requested capability. An agent has to inspect those decisions instead of assuming it received every service it requested. Functions, Object Storage, and AI Gateway require a claimed project, so the agent should preserve those requirements and ask for a claim rather than retrying or quietly omitting them.

The agent can use DATABASE_URL with standard Postgres clients and continue building. Supported Neon commands work against the temporary project too:

neon branches list
neon psql --role-name neondb_owner

The project expires after 72 hours if nobody claims it. Before claim, it is limited to 100 MB of storage and 1 GB of transfer. Those limits bound the storage, transfer, and lifetime of each unclaimed project.

The durable secret behind the short-lived token

Claimable Neon separates the registration identity from the credential used for project requests. Registration returns an identity assertion. The assertion is a durable secret, and Neon's documentation tells agents to store it like an API key.

The agent exchanges that assertion for a short-lived bearer access token. When the token expires, the agent exchanges the same assertion again. Neon does not return a refresh token.

This avoids passing a person's existing Neon API key into the agent, but it still creates a secret-handling obligation. The access token has a short lifetime and limited scope. The assertion has to remain protected until reconciliation completes, the project expires, or the registration is revoked.

A person claims the result

The claim moves the project into a person's organization and retires the temporary credentials that built it.

When the project is worth keeping, the agent asks Neon for a claim URL:

neon claim accept --no-open

The person opens the URL, signs in to Neon, chooses an organization, and accepts the transfer. The claim code lasts 15 minutes, separate from the project's 72-hour lifetime.

Generating or opening the URL does not interrupt the agent's access. When the person continues to Neon, Neon revokes the project key and current access tokens, rotates the database password, and starts a new 15-minute transfer window. If that window expires before acceptance, the project key and database password remain revoked. The identity assertion can still be exchanged for a token with no project scopes, which permits claim-status polling and a replacement claim code. Neon revokes the assertion at reconciliation.

After reconciliation, the agent discards the assertion, its access tokens, and the old DATABASE_URL. The person owns the project through the destination Neon organization.

What this implementation proves

Agents could already call provisioning APIs when someone gave them a powerful enough key. Claimable Neon draws a narrower boundary. The agent discovers the registration path itself, receives a temporary resource instead of a person's account credential, and gets an explicit decision for each optional capability. Quotas and expiration constrain anonymous use. The claim flow moves ownership to a person and invalidates the temporary credentials in defined stages.

That division is the point of auth.md. The protocol describes how an agent enters the front door. The service decides what exists behind it, how far an unclaimed agent can go, and what proof is required to keep the result.

Cloudflare and Firecrawl demonstrated the discovery and registration path across independent services. Claimable Neon applies it to stateful infrastructure with a real ownership transfer. Agents can discover each service's documented registration flow without a private integration for each agent product. User-claimed registration needs no provider participation; agent-verified registration still requires a trusted provider.

Read the original auth.md launch post for the design rationale, the API onboarding walkthrough for an implementation, and Neon's Claimable Neon reference for the complete database flow.