Neon Auth
Chooses the identity system for an app on Neon, keeps a working provider, and otherwise sets up Neon Auth (Managed Better Auth): sign-in methods, trusted domains, social OAuth and an OAuth server for MCP. Use when adding login to an app on Neon.
neon-auth- Author
- Neon
- Source
- neondatabase/agent-skills/skills/neon-auth @ d3601d9
- License
- Apache-2.0
About this skill
What it does
The skill chooses an app's identity system and, when the answer is Neon Auth, implements it. Neon Auth is Managed Better Auth: users and sessions live in the neon_auth schema of the branch's Postgres and branch with the data. The client is the @neon/auth wrapper, not bare better-auth/client.
No auth yet: Managed Better Auth. A working Better Auth, Clerk, Auth.js or Supabase Auth stays; a Neon database or Function is no reason to switch. Leaving Supabase Auth on request: Managed, though password hashes do not transfer. A feature Managed lacks: self-managed Better Auth on the app host or a Neon Function.
A plugin table dated 2026-10-30 lists what Managed supports: email and password, six social providers, email OTP, magic links, JWT, Organization in beta. MFA is on the roadmap; passkeys, API keys and SSO are not exposed. Enabling Neon Auth is auth: true in neon.ts plus neon deploy; login is a separate step. It also covers trusted domains and Apple, Microsoft and Discord OAuth with your own credentials.
references/ holds managed-auth.md (Next.js and React wiring, Better Auth UI, auth emails; production needs its own SMTP), oauth-server.md (Neon Auth as the OAuth 2.1/OIDC server for your MCP server or other clients) and self-managed.md.
When to use it, and when not
Use it to add login to an app on Neon, to leave Supabase Auth when asked, or to put OAuth in front of an MCP server.
If your auth already works, the skill will only confirm you should keep it. Managed Auth needs an AWS region and cannot be enabled with IP Allow or Private Networking.
How to run it
The install command below puts the whole folder in place. The agent picks the skill up when login or Neon Auth comes up; to call it yourself:
- Claude Code:
/neon-auth, or ask for the skill by name. - Codex:
$neon-auth. - Cursor: type
/in the Agent chat and pickneon-auth.
Example: /neon-auth Add email and GitHub sign-in to this Next.js app on Neon and protect the /dashboard route.
It first asks for the parent neon skill (neon skills -s neon -y) and configures Auth through the Neon CLI, Console or API.
How it differs from similar skills
Supabase projects treats Supabase Auth mainly as a security checklist: user_metadata in JWTs, row ownership in RLS, the service-role key. This skill chooses and wires an identity provider on Neon. Neon Functions checks the tokens it issues before a Function does any work. Neon Auth is Managed Better Auth; for self-hosted Better Auth the catalog has the author's own skills — Add authentication with Better Auth and its neighbours, including the organization and two-factor plugins, which Neon Auth supports only in part or not yet.
Install
Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.
curl -fsSL --create-dirs -o ~/.claude/skills/neon-auth/SKILL.md https://anymodel.org/en/skills/neon/neon-auth/SKILL.md -o ~/.claude/skills/neon-auth/LICENSE https://anymodel.org/en/skills/neon/neon-auth/LICENSE -o ~/.claude/skills/neon-auth/references/managed-auth.md https://anymodel.org/en/skills/neon/neon-auth/references/managed-auth.md -o ~/.claude/skills/neon-auth/references/oauth-server.md https://anymodel.org/en/skills/neon/neon-auth/references/oauth-server.md -o ~/.claude/skills/neon-auth/references/self-managed.md https://anymodel.org/en/skills/neon/neon-auth/references/self-managed.md
curl -fsSL --create-dirs -o ~/.agents/skills/neon-auth/SKILL.md https://anymodel.org/en/skills/neon/neon-auth/SKILL.md -o ~/.agents/skills/neon-auth/LICENSE https://anymodel.org/en/skills/neon/neon-auth/LICENSE -o ~/.agents/skills/neon-auth/references/managed-auth.md https://anymodel.org/en/skills/neon/neon-auth/references/managed-auth.md -o ~/.agents/skills/neon-auth/references/oauth-server.md https://anymodel.org/en/skills/neon/neon-auth/references/oauth-server.md -o ~/.agents/skills/neon-auth/references/self-managed.md https://anymodel.org/en/skills/neon/neon-auth/references/self-managed.md
foreach ($f in 'SKILL.md','LICENSE','references/managed-auth.md','references/oauth-server.md','references/self-managed.md') { $p = Join-Path "$HOME\.claude\skills\neon-auth" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/neon/neon-auth/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','LICENSE','references/managed-auth.md','references/oauth-server.md','references/self-managed.md') { $p = Join-Path "$HOME\.agents\skills\neon-auth" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/neon/neon-auth/$f" -UseBasicParsing -OutFile $p }Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/neon/neon-auth/SKILL.md
SKILL.md
FIRST: Use the parent neon skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
If the neon skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
neon skills -s neon -y
Neon Auth
Neon Auth is Managed Better Auth: users, sessions, and auth config live in the neon_auth schema on the branch's Lakebase Postgres, and auth state branches with the database. The client API is the Better Auth method set (signIn.email, signIn.social, getSession) through @neon/auth. That wrapper is not a drop-in for bare better-auth/client: it pins the plugin list and adds Neon-specific OAuth verifier, iframe popup, and JWT handling. Stay on the wrapper while Auth is managed.
This skill chooses identity, then implements Managed Better Auth. It does not replace a working auth server in order to use Postgres, Functions, Object Storage, or the AI Gateway.
When to Use
Inspect existing identity and the required login features before provisioning. A supplied DATABASE_URL is not a reason to change identity. Adding a Neon Function is not a reason to change identity.
| Situation | What to do |
|---|---|
| No existing auth | Default to Managed Better Auth. Managed setup, then references/managed-auth.md. |
| Needs a feature Managed does not offer | Self-managed Better Auth on the existing app host (Vercel or similar) or a Neon Function. Keep Lakebase Postgres. Confirm the installed Better Auth version documents that exact flow before recommending the move. If support stays unresolved, keep the current identity. references/self-managed.md. |
| Already has Better Auth | Keep it. It works with the other Neon primitives. Migrate to Managed only if the user asks. |
| User asked to migrate from Supabase Auth | Managed Better Auth. Supabase Auth. Moving only Postgres or adding a Function keeps Supabase Auth. |
| Clerk, Auth.js, Supabase Auth, or another working IdP | Keep it unless the user asks to migrate. |
Google, GitHub, Microsoft, Vercel, Apple, and Discord social OAuth are offered on Managed Auth. They are not a reason to leave Managed Auth. Microsoft, Apple, and Discord need your own credentials: Apple, Microsoft, and Discord OAuth. Making Neon Auth the OAuth server for your own MCP server or third-party OAuth clients is supported: references/oauth-server.md. Other OAuth providers, generic OAuth, MFA, passkeys, API keys, SSO, custom plugins, hooks, and custom JWT claims are the plugin matrix check.
Before enabling Managed Auth, confirm the project is on AWS and does not use IP Allow or Private Networking. Leave those protections in place.
Configure supported Managed plugins through Neon (Console, API, or neon neon-auth), not by passing plugins into @neon/auth. Enabling auth: true is not implementing login.
What It Does
- Managed identity in Postgres — users and sessions in
neon_auth, queryable with SQL, compatible with RLS. - Auth emails without an app mailer — verification, email OTP, magic links, and password reset. Getting started uses shared SMTP (
[email protected]). You do not add Resend or SendGrid to implement login. Production needs custom SMTP: https://neon.com/docs/auth/production-checklist.md - Branches with the database — each branch has its own Auth URL and isolated auth state.
- Better Auth client methods via the Neon SDK —
@neon/auth(auth only) or@neon/neon-js/auth(combined SDK). Optional UI: Better Auth UI (@better-auth-ui/reactwith its shadcn/ui components). - Fixed plugin set — the Managed client does not accept a
pluginsoption. See plugin support.
Availability
Managed Better Auth is generally available. AWS regions only. It cannot be enabled on a project with IP Allow or Private Networking.
Organization is separately Partial / Beta. Hosting self-managed Better Auth in a Neon Function follows Functions availability and claim rules; use the neon-functions skill for that host. An unclaimed project that can enable Auth still cannot use Functions until claim.
Managed setup
Merge Auth into the existing neon.ts. Do not replace other fields:
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
auth: true,
});
neon deploy
neon neon-auth status
If Function env in that config reads process.env, use neon deploy --env <file> as the parent skill describes. The manual service command is neon neon-auth enable; do not run both enable and deploy as redundant required steps when neon.ts already declares auth: true.
Then implement login: references/managed-auth.md. To make Neon Auth the OAuth server for an MCP server or OAuth clients, continue to references/oauth-server.md.
Claimable projects: follow the parent Claimable path, then auth: true and neon deploy when login is requested and no existing provider should be preserved.
Supabase Auth
When the user asked to migrate login from Supabase Auth, recommend Managed Better Auth and follow https://neon.com/docs/auth/migrate/from-supabase.md. Moving only Postgres or adding a Function is not that request: keep Supabase Auth.
SupabaseAuthAdapter() keeps method shapes such as signInWithPassword and signInWithOAuth. Those calls are not interchangeable with default Better Auth examples (signIn.email). Keep an existing adapter caller on that API.
Inventory the auth methods and database calls actually used:
- Password hashes cannot transfer. Users create new accounts or sign in with OAuth.
- Do not promise unchanged user IDs, sessions, or account linking. Plan application foreign keys with the owner.
updateUser()cannot change email or password on Managed Auth. Email verification needs application UI (codes work on shared SMTP; links need custom SMTP).- The migration guide lists Supabase phone/SMS/WhatsApp, SAML, and Web3 as unsupported on Managed Auth. Confirm the installed Better Auth version if the user still needs that exact flow; if support stays unresolved, keep Supabase Auth and stop the auth cutover. That page's "no phone auth" claim is about Supabase phone sign-in, not the constrained Managed Phone Number plugin (existing users link a number).
@supabase/supabase-jsused only for Auth does not justify enabling the Data API. Keep Data API only for existing PostgREST / Supabase database-client queries.
Verification
Managed path: sign-up, sign-in, sign-out, session restoration after reload, and protected access, including error and loading states. Exercise email verification (code on shared SMTP) when it is on. Report any flow that remains unverified.
A required plugin on the self-managed path is verified in that app's Better Auth setup, not as a Managed flow.
Plugin support
Checked 2026-10-30 against https://neon.com/docs/auth/guides/plugins.md, https://neon.com/docs/auth/guides/plugins/oauth-provider.md, https://neon.com/docs/auth/roadmap.md, and the @neon/auth client plugin list. Discord row checked 2026-11-11 against https://neon.com/docs/reference/api/auth/add-branch-neon-auth-oauth-provider.md; Discord: see Apple, Microsoft, and Discord OAuth. Re-fetch those pages if this skill may be stale. An unlisted upstream plugin needs a live check; do not treat absence from this table as a dated roadmap item.
"Not exposed" means the Managed SDK/UI contract. It is not a claim that every raw server request was tested.
| Feature | Managed Auth | Boundary |
|---|---|---|
| Email/password | Supported | signUp.email, signIn.email |
| Social OAuth (Google, GitHub, Microsoft, Vercel, Apple, Discord) | Supported | signIn.social. Shared Google credentials are for development; production and GitHub/Vercel need your own OAuth apps. Microsoft, Apple, and Discord always need your own. Discord: see details. https://neon.com/docs/auth/guides/setup-oauth.md |
| Admin | Supported | Admin session required. Plugin customization is on the roadmap. |
| Email OTP | Supported | Managed delivery. emailOtp.sendVerificationOtp, signIn.emailOtp. |
| Magic Link | Supported | Enable on the branch (off by default). signIn.magicLink. |
| Organization | Partial, Beta | Members, invitations, owner/admin/member. No Teams, server hooks, custom roles/permissions, or dynamic access control. Emailed invitations: managed-auth.md. |
| JWT | Supported | EdDSA (Ed25519), 15-minute expiry, no custom claims. Default client: .token() then data.token. SupabaseAuthAdapter(): getSession() then data.session.access_token (no .token()). |
| Open API | Supported | Server routes /reference and /open-api/generate-schema. |
| Phone Number | Supported with constraints | Browser client: existing users link a number, then sign in; no phone-first signup; own SMS webhook; custom UI. Next.js auth.handler() forwards the catch-all path, including phone OTP. A missing auth.phoneNumber server method is a missing typed helper, not a proxy rejection. https://neon.com/docs/auth/guides/plugins/phone-number.md |
| MFA / Two-Factor | Roadmap | Unavailable on Managed Auth. If required: self-managed.md, after confirming the installed Better Auth version. |
| Passkey, API Key, Generic OAuth, One Tap, Multi Session | Not exposed by Managed SDK/UI | If required: self-managed.md. Generic OAuth is not Google/GitHub/Microsoft/Vercel/Apple/Discord social sign-in. |
| OAuth Provider (OAuth server, MCP auth) | Supported (beta) | Neon Auth is the OAuth 2.1 / OIDC server for your MCP server or third-party OAuth clients. You host the login and consent pages; no client credentials grant. See references/oauth-server.md. |
| SSO / SAML | Not listed or exposed | If required: self-managed.md, after confirming the installed Better Auth version. |
The default Managed client method is getAnonymousToken(). That JWT is a Neon anonymous Data API token. It is not Better Auth's Anonymous-account plugin (signIn.anonymous). anonymousTokenClient() is the SDK plugin factory, not a method on the public client. Do not call it, and do not call getAnonymousToken() on SupabaseAuthAdapter().
Trusted domains and webhooks are Neon settings, not installable Better Auth plugins.
Apple, Microsoft, and Discord OAuth
Apple, Microsoft, and Discord reject shared credentials. Add them with your own via neon neon-auth oauth-provider add|update (Console and API work too). A multi-line secret goes in a file with --oauth-client-secret-file, not inline.
- Apple:
client_idis the Services ID,client_secretis the full.p8private key. Also pass--apple-team-idand--apple-key-id(10 characters). Neon Auth signs the client-secret JWT itself, so there is nothing to rotate. Rotating the key needs the new--apple-key-idin the same update. The return URL must be HTTPS (https://<auth host>/<db>/auth/callback/apple); Apple rejects localhost, so test through a tunnel or a deployed preview. - Microsoft:
client_idandclient_secretfrom the Entra app registration.--microsoft-tenant-idis optional:common(default),organizations,consumers, a tenant GUID, or a domain. The redirect URI is<base_url>/callback/microsoft. - Microsoft email verification: an email counts as verified only when the ID token carries
xms_edov= true andacct= 0. Addxms_edovandacctas optional ID-token claims in Entra. Without them, a same-email existing user getsaccount_not_linked,link-socialfails withunable_to_link_account, and new users stay unverified. - Discord: Always needs your own Discord application
client_idandclient_secret(shared is rejected on add and update). Better Auth only; legacy Stack Auth returns 422. Scopes areidentifyandemail. Redirect URI<base_url>/callback/discord. With Neon CLI 9.5.0 or later, add or update it like Microsoft using--provider-id discord,--oauth-client-id, and--oauth-client-secret-file(preferred to keep the secret out of shell history). Delete it withneon neon-auth oauth-provider delete --provider-id discord. Older CLIs can use MCPauth.oauthProviders.add|update|deleteor the API: https://neon.com/docs/reference/api/auth/add-branch-neon-auth-oauth-provider.md - Discord email verification: an email counts as verified only when Discord's
verifiedis the booleantrue. An unverified Discord email cannot auto-link to an existing same-email user, and a new user from it is stored as unverified. A Discord account with no email fails withemail_not_found.
Trusted domains
Auth redirects only to origins on its allowlist. invalid domain means the app origin is missing. Include the scheme, omit a trailing slash, register production and preview origins before pointing users at them, and target the correct branch:
neon neon-auth domain add https://app.example.com
neon neon-auth domain list
neon neon-auth domain delete https://old.example.com
Localhost ports are pre-approved by default. An existing project can have that off: neon neon-auth domain allow-localhost get|enable|disable. Docs: https://neon.com/docs/auth/guides/configure-domains.md
OAuth provider redirect is {NEON_AUTH_BASE_URL}/callback/{provider} (the Auth URL includes its path). callbackURL on signIn.social is the later app landing origin and must be trusted.
The Managed SDK handles iframe OAuth popup and neon_auth_session_verifier. Keep the wrapper, callback route, and middleware. Do not reimplement that flow, and do not promise third-party cookies in every browser.
Functions and Data API
A Function authenticates whoever already signs the user in. Do not switch identity to call a Function. Verify the token in the neon-functions skill and https://neon.com/docs/compute/functions/authentication.md.
Managed Auth: injected NEON_AUTH_JWKS_URL, issuer from NEON_AUTH_BASE_URL. Token: default client .token() then data.token; SupabaseAuthAdapter() getSession() then data.session.access_token. A valid token is not permission to read another user's rows. Sign-out ends the browser session; do not claim it immediately revokes an already-issued JWT.
Data API identity: references/managed-auth.md. New apps query Postgres from Functions or existing handlers, not the Data API.
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel