Enable Neon Auth for the branch

Enables Neon Auth for the specified branch by connecting it to an authentication provider.

POST /projects/{project_id}/branches/{branch_id}/authbeta

Enables Neon Auth for the specified branch by connecting it to an authentication provider. Creating the integration provisions the neon_auth schema in the branch database, which stores user identity data synchronized from the provider.

Markdown for AI context

REST API - curl

curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/auth" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"

Also available in

Bash

neon neon-auth enable

Tool: provision_neon_auth

Provisions Neon Auth for a Neon branch. Neon Auth is a managed authentication service built on Better Auth, fully integrated with Lakebase Postgres and the rest of the Neon backend primitives. The tool will: 1. Create the neon_auth schema in your database to store users, sessions, project configs and organizations 2. Set up secure Auth related APIs for your branch 3. Deploy an auth service in the same region as your Neon compute for low-latency requests 4. Return the Auth URL specific to your branch, along with credentials for your application - Branch-compatible: Auth data (users, sessions, config) branches with your database - Google and GitHub OAuth included out of the box - Works with RLS: JWTs are validated by the Data API for authenticated queries - Better Auth compatible: Exposes the same APIs and schema as Better Auth

projectId (string, required) The ID of the project to provision Neon Auth for
branchId (string, optional) An optional ID of the branch to provision Neon Auth for. If not provided, the default branch is used.
databaseName (string, optional) The database name to provision Neon Auth for. If not provided, the default database is used.

Console path: Projects → Auth

Parameters

Project ID

project_id

string

The Neon project ID

Branch ID

branch_id

string

The Neon branch ID

Request body

1 required Required: auth_provider.

Auth provider

auth_provider

string

Authentication provider integrated with this Neon Auth configuration. better_auth integrates with Better Auth (the current, recommended provider). stack integrates with Stack Auth (deprecated). mock is a simulated provider for local development and testing only.

mockstackbetter_auth

Database name

database_name

string

Name of the database to enable Neon Auth on. When omitted, the integration uses the project's default database.

Response

201

Enables Neon Auth integration for the branch

Depth

"auth_provider": (string),reqmock | stack | better_auth

"auth_provider_project_id": (string),req

"pub_client_key": (string),req

"secret_server_key": (string),req

"jwks_url": (string),req

"schema_name": (string),req

"table_name": (string),req

"base_url": (string),

Errors

default

General error

This endpoint can return the standard Neon API error response.

Response fields

message Required. Human-readable error message.
code Required. Machine-readable error code.
request_id Optional. Request identifier for debugging. You can provide one with the X-Request-ID header.

Retry guidance

If no response is returned, the request may still have reached the server. This is why retry safety depends on the method and status code.

Idempotent methods (GET, HEAD, OPTIONS) are generally safe to retry after a network error or timeout. Non-idempotent methods (POST, PATCH, DELETE, PUT) can change state, so avoid automatic retries unless your workflow can tolerate duplicate effects.

Responses with 423 Locked or 503 Service Unavailable are safe to retry. 423 Locked means the resource is temporarily locked, usually because another operation is in progress.