Connect your app

Credentials are branch-scoped. Each branch has its own isolated credentials and data, whether it is your default branch (for example, main) or a child branch you use for development, testing, or preview deployments.

A child branch is a copy-on-write clone of its parent, so it starts with isolated credentials and its own copy of the data. You can test your app with real authentication workflows and real storage without touching your default branch. See Develop with preview branches below.

You can get connection details from the Console, CLI, or API.

• Console
• CLI
• API

In the Neon Console, select your project and branch and click Connect to open the Connect to your branch modal.

For Postgres credentials, use neon connection-string:

neon connection-string mybranch --database-name mydb --role-name myrole

To pull all credentials for a branch (including Object Storage, Data API, Auth, and Functions if declared in neon.ts), use neon env pull:

neon env pull --branch mybranch --file .env.local

By default, neon env pull writes DATABASE_URL, DATABASE_URL_UNPOOLED, and NEON_BRANCH. With a neon.ts file declaring services, it also writes credentials for each service. Use --service to pull only specific services:

neon env pull --service postgres --service object-storage

For Postgres, fetch the connection string with GET /api/v2/projects/{project_id}/connection_uri:

curl "https://console.neon.tech/api/v2/projects/{project_id}/connection_uri?branch_id={branch_id}&database_name={database_name}&role_name={role_name}" \
  -H "Authorization: Bearer $NEON_API_KEY"

For Object Storage credentials, use POST /api/v2/projects/{project_id}/branches/{branch_id}/credentials with storage:read and storage:write scopes. For Data API and Auth, see Managing the Data API and Manage Auth via the API.

Store credentials in .env files for local development, in your CI secrets manager for CI/CD workflows, or let Neon Functions auto-inject them if you are deploying to Neon Functions.

Local development

Use neon env pull to write credentials to .env.local (or .env):

neon env pull --file .env.local

This writes DATABASE_URL, DATABASE_URL_UNPOOLED, NEON_BRANCH, and (if you have a neon.ts declaring services) credentials for Object Storage (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, AWS_REGION), Data API, and Auth.

Production and CI

For production deployments, store credentials in your secrets manager (AWS Secrets Manager, Vercel environment variables, GitHub Secrets, etc.). Fetch credentials from the Console, CLI, or API, then set them in your platform's secrets configuration.

Neon Functions

A deployed Neon Function gets credentials injected automatically for every service enabled on its branch. Enable Object Storage and the AWS_* credentials are in process.env with no manual setup. Declaring buckets in neon.ts is what pulls those credentials into your local .env (see Local development above) and gives you type-safe access. See Neon Functions environment variables.

Use the credentials for your selected branch with each enabled service.

import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);
const rows = await sql`SELECT * FROM users`;

import { S3Client } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  forcePathStyle: true,
});

import OpenAI from 'openai';
import 'dotenv/config';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});
const response = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);

import { createAuthClient } from '@neondatabase/neon-js/auth';

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);

When you create a child branch from your default branch, the child branch gets its own credentials that are valid only for that branch and its descendants. This means you can test authentication workflows, storage uploads, and data changes in a development, test, or preview environment without affecting your default branch.

Credentials are branch-scoped: a credential created on a branch is valid for that branch and any branches descended from it. It's not valid for branches outside that lineage. See How branch binding works for details.

To automate preview branches, use GitHub Actions or the Vercel integration. For how branches work, see Get started with branching.