Beta
Neon Auth is in beta and ready to use. We're actively improving it based on feedback from developers like you. Share your experience in our Discord or via the Neon Console.
Related docs
Sample project
Learn how to manage your Neon Auth integration using the Neon API. Create a new integration, generate SDK keys, add users, and claim ownership of your Neon-managed auth project to your auth provider.
Prerequisites
- A Neon API key (see Create an API Key)
- A Neon project
Common parameters
Several endpoints require these parameters:
project_id
: Your Neon project ID. You can find it in the Neon Console on the Settings page, or use the List Projects endpoint.auth_provider
: The authentication provider you're using. Currently supported providers:stack
: Stack Auth integration
Create integration
Creates a Neon-managed authentication project for your database (currently supporting Stack Auth). This endpoint performs the same action as using Quick Start in the Console, automatically provisioning and configuring a new auth provider project that Neon manages for you.
note
To create an integration, you'll need:
- Your production branch ID. Get it from the Neon Console on the Branches page, or use the List Branches endpoint (look for
"default": true
) - Your database name and role name. Get them by clicking on the Connect button on your Project Dashboard in the Neon Console, or use the List Databases endpoint
Required parameters:
project_id
: Your Neon project IDbranch_id
: Your project's production branch IDdatabase_name
: Name of your database (defaults to"neondb"
)role_name
: Database role for authenticated users (defaults to"neondb_owner"
)
curl --request POST \
--url 'https://console.neon.tech/api/v2/projects/auth/create' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"auth_provider": "stack",
"project_id": "project-id",
"branch_id": "br-example-123",
"database_name": "neondb",
"role_name": "neondb_owner"
}' | jq
Example response:
{
"auth_provider": "stack",
"auth_provider_project_id": "proj-example-123",
"pub_client_key": "pck_example123",
"secret_server_key": "ssk_example123",
"jwks_url": "https://api.stack-auth.com/api/v1/projects/proj-example-123/.well-known/jwks.json",
"schema_name": "neon_auth",
"table_name": "users_sync"
}
List integrations
Lists all active auth provider integrations for your project.
curl --request GET \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/integrations' \
--header 'authorization: Bearer $NEON_API_KEY' | jq
Example response:
{
"data": [
{
"auth_provider": "stack",
"auth_provider_project_id": "proj-example-123",
"branch_id": "br-example-123",
"db_name": "neondb",
"created_at": "2024-03-19T12:00:00Z",
"owned_by": "neon",
"jwks_url": "https://api.stack-auth.com/api/v1/projects/proj-example-123/.well-known/jwks.json"
}
]
}
Generate SDK keys
Generates SDK keys for your auth provider integration. These keys are used to set up your frontend and backend SDKs.
Required parameters:
project_id
: Your Neon project IDauth_provider
: The authentication provider (currently"stack"
)
curl --request POST \
--url 'https://console.neon.tech/api/v2/projects/auth/keys' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"project_id": "project-id",
"auth_provider": "stack"
}' | jq
Example response:
{
"auth_provider": "stack",
"auth_provider_project_id": "project-id-123",
"pub_client_key": "pck_example...",
"secret_server_key": "ssk_example...",
"jwks_url": "https://api.stack-auth.com/api/v1/projects/project-id-123/.well-known/jwks.json",
"schema_name": "neon_auth",
"table_name": "users_sync"
}
Create users
Creates a new user in your auth provider's system.
Required parameters:
project_id
: Your Neon project IDauth_provider
: The authentication provider (currently"stack"
)email
: User's email address
Optional parameters:
name
: User's display name (1-255 characters)
curl --request POST \
--url 'https://console.neon.tech/api/v2/projects/auth/user' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"project_id": "project-id",
"auth_provider": "stack",
"email": "user@example.com",
"name": "Example User"
}' | jq
Example response:
{
"id": "user-id-123"
}
You can verify the user was synchronized to your database by connecting to your project and querying the neon_auth.users_sync
table:
psql postgres://[user]:[password]@[hostname]/[database]
SELECT id, email, name, created_at FROM neon_auth.users_sync;
Transfer to your auth provider
Transfer ownership of your Neon-managed auth project to your own auth provider account. This is a two-step process:
- Request a transfer URL:
curl --request POST \
--url 'https://console.neon.tech/api/v2/projects/auth/transfer_ownership' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"project_id": "project-id",
"auth_provider": "stack"
}' | jq
Example response:
{
"url": "https://app.stack-auth.com/integrations/neon/projects/transfer/confirm?code=example123"
}
- Open the returned URL in a browser to complete the transfer. You'll be asked to confirm which Stack Auth account should receive ownership of the project.
note
After the transfer, you'll still be able to access your project from the Neon dashboard, but you'll also have direct access from the Stack Auth dashboard.
Delete integration
Removes an integration with a specific auth provider.
curl --request DELETE \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/integration/{auth_provider}' \
--header 'authorization: Bearer $NEON_API_KEY' | jq
Manage OAuth providers via API
You can programmatically manage OAuth providers for your Neon Auth project using the Neon API. The following endpoints allow you to add, list, update, and delete OAuth providers for a project.
List OAuth providers
Lists the OAuth providers for the specified project.
Required parameters:
project_id
(string): The Neon project ID
curl --request GET \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/oauth_providers' \
--header 'authorization: Bearer $NEON_API_KEY'
Example response:
{
"providers": [
{ "id": "github", "type": "shared" },
{ "id": "google", "type": "shared" }
]
}
Add an OAuth provider
Adds an OAuth provider to the specified project.
Required parameters:
project_id
(string): The Neon project IDid
(string): The provider ID (e.g.,google
,github
,microsoft
)
Optional parameters:
client_id
(string): The OAuth client IDclient_secret
(string): The OAuth client secret
If you do not provide
client_id
andclient_secret
, Neon will use shared keys for the provider. For production environments, you should always provide your ownclient_id
andclient_secret
to ensure security and control. See Production OAuth setup best practices for details.
curl --request POST \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/oauth_providers' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"id": "google",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
}'
Example response:
{
"id": "google",
"type": "standard",
"client_id": "your-client-id",
"client_secret": "your-client-secret"
}
Update an OAuth provider
Updates an OAuth provider for the specified project.
Required parameters:
project_id
(string): The Neon project IDoauth_provider_id
(string): The OAuth provider ID (e.g.,google
,github
,microsoft
)
Optional parameters (request body):
client_id
(string): The new OAuth client IDclient_secret
(string): The new OAuth client secret
curl --request PATCH \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/oauth_providers/google' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"client_id": "new-client-id",
"client_secret": "new-client-secret"
}'
Example response:
{
"id": "google",
"type": "standard",
"client_id": "new-client-id",
"client_secret": "new-client-secret"
}
Delete an OAuth provider
Deletes an OAuth provider from the specified project.
Required parameters:
project_id
(string): The Neon project IDoauth_provider_id
(string): The OAuth provider ID (e.g.,google
,github
,microsoft
)
curl --request DELETE \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/oauth_providers/google' \
--header 'authorization: Bearer $NEON_API_KEY'
A successful DELETE returns no response body (204 No Content
).
You can use the GET endpoint to confirm the provider has been removed.
Get email server configuration
Gets the email server configuration for the specified project.
Required parameters:
project_id
: Your Neon project ID
curl --request GET \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/email_server' \
--header 'accept: application/json' \
--header 'authorization: Bearer $NEON_API_KEY' | jq
Example response:
{
"type": "shared"
}
Update email server configuration
Updates the email server configuration for the specified project.
Required parameters:
project_id
: Your Neon project ID
Request body parameters:
type
: Type of email server,"shared"
or"standard"
(standard = custom email server)host
: SMTP server hostname (required for custom SMTP)port
: SMTP server port (required for custom SMTP)username
: SMTP username (required for custom SMTP)password
: SMTP password (required for custom SMTP)sender_email
: Email address that will appear as the sender (required for custom SMTP)sender_name
: Name that will appear as the sender (required for custom SMTP)
curl --request PATCH \
--url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/email_server' \
--header 'accept: application/json' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
"type": "standard",
"host": "smtp.gmail.com",
"port": 587,
"username": "your-email@gmail.com",
"password": "your-app-password",
"sender_email": "noreply@yourcompany.com",
"sender_name": "Your Company"
}' | jq
Example response:
{
"type": "standard",
"host": "smtp.gmail.com",
"port": 587,
"username": "your-email@gmail.com",
"password": "your-app-password",
"sender_email": "noreply@yourcompany.com",
"sender_name": "Your Company"
}
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more details, see Getting Support.