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

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 main 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 ID
  • branch_id: Your project's main branch ID
  • database_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"
}

Try in API Reference ↗

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"
    }
  ]
}

Try in API Reference ↗

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 ID
  • auth_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"
}

Try in API Reference ↗

Create users

Creates a new user in your auth provider's system.

Required parameters:

  • project_id: Your Neon project ID
  • auth_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;

Try in API Reference ↗

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:

  1. 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"
}
  1. 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

Try in API Reference ↗