Document Claimable Neon expirations and neon deploy for Auth

[andrelandgraf]

Problem

Agents read https://neon.com/auth.md, then mint a claim link. Humans read /docs/reference/claimable-neon. Both described a 72-hour unclaimed project and a claim ceremony. Neither said that the claim code is a second, much shorter clock, or that Auth and the Data API can be added after create — including on the unclaimed project.

A 15-minute code looks like the project died. A Postgres-only create looks like Auth cannot be turned on.

Diagnosis

Two independent fields:

• project.expires_at — unclaimed project TTL, 72 hours today
• expires_in — claim code TTL, 900 seconds today

Opening verification_uri_complete does not freeze access. Continuing to Neon starts a transfer, starts a new expires_in window, and revokes the project key, access tokens, and database password. POST /v1/projects/{id}/claim again if the unused code expires, or if that transfer window expires before the human accepts. Re-issue only while project.expires_at is still in the future. claim_in_progress means the transfer window is still live.

Auth and the Data API can be requested at registration. They can also be enabled later with neon.ts and neon deploy on the unclaimed project. After claim, the same config talks to Neon directly. An external JWKS is only accepted after claim. neon checkout does not apply that to an existing branch.

After the human continues to Neon, the replacement access token has no project scopes. It authorizes claim-status polling and a replacement claim code if that transfer window expires.

The user-facing interface

https://neon.com/auth.md (this PR's public/auth.md):

POST https://claimable.neon.tech/v1/projects/<project_id>/claim
Authorization: Bearer <access_token>

The unclaimed project expires at project.expires_at (72 hours today). A claim code expires in expires_in seconds (900 today). If the unused code expires, POST this endpoint again. Each POST cancels the previous unused code and returns a new one.

Add Auth or the Data API before or after claim:

import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true,
  dataApi: true,
});

neon deploy

Data API with the default auth provider requires Auth. An external JWKS is not accepted on the unclaimed project.

The human docs page repeats that HTTP and the same neon.ts snippet. claim_in_progress now means: poll status; mint a new code after the transfer window expires.

Existing create-time Auth and Data API requests do not change.

Also in here

Hosted skill copies under public/docs/ai/skills/neon/ so the neon.com skill URL matches agent-skills#99. config/skills.json pins neon to 5460c18205b8f7a5bb3bafa173b82e5f53d7f605 so check:skills-sync compares that commit instead of main. After #99 lands, flip the pin back to main.

Skill discovery digests in public/.well-known/agent-skills/index.json (and the /docs/ copy) match the updated SKILL.md bytes.

Verification

GITHUB_TOKEN="$(gh auth token)" npm run check:skills-sync -- --skill neon

Passed against neondatabase/agent-skills@5460c182. Read public/auth.md against the docs page: both allow POST /claim again after the transfer window expires, and both document neon deploy on the unclaimed project.

No new tests. Preview after merge: https://neon.com/auth.md, https://neon.com/docs/reference/claimable-neon, https://neon.com/docs/ai/skills/neon/references/claimable-neon.md.

For your attention

• Merge agent-skills#99 before this, or the pin is load-bearing.
• After release notes cleanup #99 is on main, set config/skills.json neon.ref back to main.
• This does not announce Claimable Neon. It documents the live protocol.
• OpenAI, Grok, and JetBrains marketplace skill copies are not in this repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
neon-next	Ready	Preview	Aug 26, 2026 10:40pm