AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
Neon Auth provides a managed authentication service built on Better Auth, with user data and sessions stored directly in the project's Lakebase Postgres schema. It integrates seamlessly with Neon's branching model, ensuring that authentication state is isolated per branch. The service supports standard authentication flows like email/password, social OAuth, and magic links, while also offering capabilities to act as an OAuth 2.1/OIDC server for third-party clients or MCP servers. It is designed to be the default choice for new applications on Neon, while allowing for self-managed alternatives if specific advanced requirements are needed.
What it does
- Manages user identity and sessions within a dedicated neon_auth Postgres schema.
- Provides authentication methods via the @neon/auth SDK wrapper.
- Supports social OAuth providers including Google, GitHub, Microsoft, Vercel, and Apple.
- Enables email-based authentication including OTP, magic links, and password resets.
- Allows the project to act as an OAuth 2.1/OIDC server for external applications.
- Integrates with Neon database branching to maintain isolated auth states.
When to use it
- When starting a new application on Neon and requiring a managed authentication solution.
- When migrating from Supabase Auth to a managed Postgres-native auth service.
- When you need to act as an OAuth provider for your own MCP servers or third-party clients.
- When you require authentication state to branch automatically alongside your database.
Advantages
- Native integration with Neon database branching and schema management.
- Reduces infrastructure overhead by using managed auth services instead of external IdPs.
- Provides a consistent SDK experience across Neon-hosted applications.
- Supports secure OAuth 2.1/OIDC server functionality for custom integrations.
Usage examples
- “Add authentication to my new Neon app.”
- The agent will configure Managed Better Auth by setting auth: true in the project's neon.ts file and guide the implementation of login methods.
- “Migrate my app from Supabase Auth to Neon.”
- The agent will recommend Managed Better Auth, provide the migration guide, and assist in inventorying existing auth methods.
- “Set up my Neon project as an OAuth server for my MCP client.”
- The agent will configure the oauth-server plugin, define the login/consent pages, and register the necessary OAuth clients.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/neondatabase/neon-auth/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip neon-auth.zip -d .agents/skills
Documentation by Neon
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 -yNeon 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, and Apple social OAuth are offered on Managed Auth. They are not a reason to leave Managed Auth. Microsoft and Apple need your own credentials: Apple and Microsoft 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.mdBranches 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 statusIf 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. 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) | Supported | signIn.social. Shared Google credentials are for development; production and GitHub/Vercel need your own OAuth apps. Microsoft and Apple always need your own (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 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 and Microsoft OAuth
Both providers 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.
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.comLocalhost 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.
Files
- ATTRIBUTION.mdAdded by AutoGineer862 B
- LICENSELicence file added by AutoGineer11.1 KiB
- SKILL.md14.0 KiB
- references/managed-auth.md12.6 KiB
- references/oauth-server.md10.7 KiB
- references/self-managed.md1.8 KiB
LICENSE
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs an MCP server, Needs network access, Needs an API key
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Neon
- Publisher
- Neon (Official)
- Source
- neondatabase/agent-skills · skills/neon-auth · commit 2b0e2b6
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
- Also distributed in
- neondatabase/agent-skills
AutoGineer is not affiliated with or endorsed by Neon or Neon.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download neon-auth.zip