---
title: Neon OAuth integration
enableTableOfContents: true
updatedOn: '2025-05-30T16:54:40.477Z'
---
You can integrate your application or service with Neon using OAuth. The Neon OAuth integration enables your application to interact with Neon user accounts, carrying out permitted actions on their behalf. Our integration does not require direct access to user login credentials and is conducted with their approval, ensuring data privacy and security.
To set up the integration and create a Neon OAuth application, you can apply on our [Partners page](/partners). You will need to provide the following information:
- Your name and email address (this should be an individual email address, not a shared inbox address)
- Your company name
- Details about your application, including your application name, what it does, and a link to the website.
- Callback URL(s), which are used to redirect users after completing the authorization flow.
```text
https://app.company.com/api/integrations/neon/callback
https://app.stage.company.com/api/integrations/neon/callback
http://localhost:3000/api/integrations/neon/callback
```
- Required scopes, defining the type of access you need. We provide scopes for managing both projects and organizations. For a list of all available scopes, see [Supported OAuth Scopes](#supported-oauth-scopes).
- Whether or not you will make API calls from a backend.
- A logo to be displayed on Neon's OAuth consent dialog when users authorize your application to access their Neon account.
After your application is reviewed, Neon will provide you with a **client ID** and, if applicable, a **client secret**. Client secrets are only provided for backend clients, so non-backend applications (e.g. browser-based apps or CLI tools) will not receive a secret. These credentials are sensitive and should be stored securely.
## How the OAuth integration works
Here is a high-level overview of how Neon's OAuth implementation works:
1. The user sends a request to your API endpoint to initiate the OAuth flow by clicking a button or link in your application.
2. An authorization URL is generated.
3. The user is redirected to Neon’s OAuth consent screen to authorize the application.
4. The user logs in and authorizes the application, granting it the necessary permissions.
5. A redirect is performed to a callback endpoint, which includes an access token that allows the application to manage Neon resources on the user’s behalf.
## About the Neon OAuth server
The Neon OAuth server implements the OpenID Connect protocol and supports [OpenID Connect Discovery specification](https://openid.net/specs/openid-connect-discovery-1_0.html). The server metadata is published at the following well-known URL: [https://oauth2.neon.tech/.well-known/openid-configuration](https://oauth2.neon.tech/.well-known/openid-configuration).
Here is an example response:
```json
{
"issuer": "https://oauth2.neon.tech/",
"authorization_endpoint": "https://oauth2.neon.tech/oauth2/auth",
"token_endpoint": "https://oauth2.neon.tech/oauth2/token",
"jwks_uri": "https://oauth2.neon.tech/.well-known/jwks.json",
"subject_types_supported": ["public"],
"response_types_supported": [
"code",
"code id_token",
"id_token",
"token id_token",
"token",
"token id_token code"
],
"claims_supported": ["sub"],
"grant_types_supported": [
"authorization_code",
"implicit",
"client_credentials",
"refresh_token"
],
"response_modes_supported": ["query", "fragment"],
"userinfo_endpoint": "https://oauth2.neon.tech/userinfo",
"scopes_supported": ["offline_access", "offline", "openid"],
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic",
"private_key_jwt",
"none"
],
"userinfo_signing_alg_values_supported": ["none", "RS256"],
"id_token_signing_alg_values_supported": ["RS256"],
"request_parameter_supported": true,
"request_uri_parameter_supported": true,
"require_request_uri_registration": true,
"claims_parameter_supported": false,
"revocation_endpoint": "https://oauth2.neon.tech/oauth2/revoke",
"backchannel_logout_supported": true,
"backchannel_logout_session_supported": true,
"frontchannel_logout_supported": true,
"frontchannel_logout_session_supported": true,
"end_session_endpoint": "https://oauth2.neon.tech/oauth2/sessions/logout",
"request_object_signing_alg_values_supported": ["RS256", "none"],
"code_challenge_methods_supported": ["plain", "S256"]
}
```
You must add `offline` and `offline_access` scopes to your request to receive the `refresh_token`.
Depending on the OpenID client you’re using, you might not need to explicitly interact with the API endpoints listed below. OAuth 2.0 clients typically handle this interaction automatically. For example, the [Neon CLI](/docs/reference/neon-cli), written in Typescript, interacts with the API endpoints automatically to retrieve the `refresh_token` and `access_token`. For an example, refer to this part of the Neon CLI [source code](https://github.com/neondatabase/neonctl/blob/3764c5d5675197ef9bc7ed78d5531bd318f7f13b/src/auth.ts#L63-L81). In this example, the `oauthHost` is `https://oauth2.neon.tech`.
## Supported OAuth Scopes
The following OAuth scopes allow varying degrees of access to Neon resources:
| **Project scopes** | **Scope Name** |
| :----------------- | :---------------------------------- |
| Create Projects | `urn:neoncloud:projects:create` |
| Read Projects | `urn:neoncloud:projects:read` |
| Modify Projects | `urn:neoncloud:projects:update` |
| Delete Projects | `urn:neoncloud:projects:delete` |
| Manage Projects | `urn:neoncloud:projects:permission` |
| **Organization scopes** | **Scope Name** |
| :------------------------------ | :------------------------------ |
| Create Organizations | `urn:neoncloud:orgs:create` |
| Read Organizations | `urn:neoncloud:orgs:read` |
| Update Organizations | `urn:neoncloud:orgs:update` |
| Delete Organizations | `urn:neoncloud:orgs:delete` |
| Manage Organization Permissions | `urn:neoncloud:orgs:permission` |
You must choose from these predefined scopes when requesting access; custom scopes are not supported.
Let's now go through the full flow, step by step:
## Initiating the OAuth flow
To initiate the OAuth flow, you need to generate an authorization URL. You can do that by directing your users to `https://oauth2.neon.tech/oauth2/auth` while passing the following query parameters:
- `client_id`: your OAuth application's ID (provided to you by Neon after your application is received)
- `redirect_uri`: the full URL that Neon should redirect users to after authorizing your application. The URL should match at least one of the callback URLs you provided when applying to become a partner.
- `scope`: This is a space-separated list of predefined scopes that define the level of access you want to request. For a full list of supported scopes and their meanings, see the [Supported OAuth Scopes](#supported-oauth-scopes) section.
**Example:**
```text
urn:neoncloud:projects:create urn:neoncloud:projects:read urn:neoncloud:projects:update urn:neoncloud:projects:delete urn:neoncloud:orgs:read
```
- `response_type`: This should be set to `code` to indicate that you are using the [Authorization Code grant type](https://oauth.net/2/grant-types/authorization-code/).
- `code_challenge`: This is a random string that is used to verify the integrity of the authorization code.
- `state`: This is a random string that is returned to your callback URL. You can use this parameter to verify that the request came from your application and not from a third party.
## Authorization URL
Here is an example of what the authorization URL might look like:
```text
https://oauth2.neon.tech/oauth2/auth?client_id=neon-experimental&scope=openid%20offline%20offline_access%20urn%3Aneoncloud%3Aprojects%3Acreate%20urn%3Aneoncloud%3Aprojects%3Aread%20urn%3Aneoncloud%3Aprojects%3Aupdate%20urn%3Aneoncloud%3Aprojects%3Adelete&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fauth%2Fcallback%2Fneon&grant_type=authorization_code&state=H58y-rSTebc3QmNbRjNTX9dL73-IyoU2T_WNievO9as&code_challenge=99XcbwOFU6iEsvXr77Xxwsk9I0GL4c4c4Q8yPIVrF_0&code_challenge_method=S256
```
## OAuth consent screen
After being redirected to the authorization URL, the user is presented with Neon's OAuth consent screen, which is pre-populated with the scopes you requested. From the consent screen, the user is able to review the scopes and authorize the application to connect their Neon account.
The [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api) provides a [Get current user details](https://api-docs.neon.tech/reference/getcurrentuserinfo) endpoint for retrieving information about the currently authorized Neon user.
## Authorization code is returned to your callback URL
After successfully completing the authorization flow, the user is redirected to the callback URL with the following query parameters appended to the URL:
- `code`: an authorization code that will be exchanged for an access token
- `scope`: the scopes that the user authorized your application to access
- `state`: you can compare the value of this parameter with the original `state` you provided in the previous step to ensure that the request came from your application and not from a third party
## Exchanging the authorization code for an access token
You can now exchange the authorization code returned from the previous step for an access token. To do that, you need to send a `POST` request to `https://oauth2.neon.tech/oauth2/token` with the following parameters:
- `client_id`: your OAuth application's ID.
- `redirect_uri`: the full URL that Neon should redirect users to after authorizing your application. The URL should match at least one of the callback URLs you provided when applying to become a partner.
- `client_secret`: your OAuth application's secret
- `grant_type`: set this to `authorization_code` to indicate that you are using the [Authorization Code grant type](https://oauth.net/2/grant-types/authorization-code/)
- `code`: the authorization code returned from the previous step
The response object includes an `access_token` value, required for making requests to the [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api) on your users' behalf. This value must be supplied in the Authorization header of the HTTP request when sending requests to the Neon API.
## Example OAuth applications
For an example application that leverages the Neon OAuth integration, see the [Visualizing Neon Database Branches](https://neon-experimental.vercel.app) application. You can find the application code on GitHub.
Neon Branches Visualizer