Object storage authentication

Neon Object Storage uses the same scoped-credential system as AI Gateway: one credential API mints branch-scoped tokens that differ by scope (Object Storage uses storage:read and storage:write). You create a scoped credential via the Neon API, and it maps directly to the S3 Access Key ID and Secret Access Key your SDK expects. No AWS account or IAM configuration required.

Creating a credential

An object storage credential requires at minimum one of:

• storage:read: allows GetObject, HeadObject, ListObjects, and ListBuckets
• storage:write: allows all read operations plus PutObject and DeleteObject

AWS_ENDPOINT_URL_S3=https://br-cool-darkness-a1b2c3d4.storage.c-1.us-east-2.aws.neon.build
AWS_ACCESS_KEY_ID=nak_live_...
AWS_SECRET_ACCESS_KEY=nsk_live_...
AWS_REGION=us-east-2

Mapping to your S3 SDK

Configure your S3 client using these values:

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!,   // token_id
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!, // s3_secret_access_key
  },
  forcePathStyle: true,
});

Pull credentials with neon

For local development, neon env pull writes storage credentials to your .env file automatically. No manual copy-paste from the API response:

neon env pull --file .env.local

This populates AWS_ENDPOINT_URL_S3, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION for the current branch alongside your database connection string. To check the current credential status:

neon config status

For production deployments, use the API-based workflow to create named, scoped credentials.

Read vs write scopes

Issue separate credentials for read and write access when you want to limit exposure:

• Server-side code that uploads files: storage:write (includes read)
• Client-side or CDN code that only fetches: storage:read
• Presigned URLs: generate these server-side from a storage:write credential. The URL itself requires no credential in the browser.

The S3 data plane enforces scope on every request. A credential without a storage scope returns 403 AccessDenied on all S3 operations. Server-side COPY requires both storage:read and storage:write.

Credentials in Neon Functions

When your code runs inside Neon Functions, Neon injects storage credentials automatically. You don't need to create a credential:

See Environment variables for the full list of variables Neon injects into a function.

Credentials are branch-scoped and tied to the function's serving branch. Injected values are defaults, not reserved names: a user-supplied environment variable with the same name (set via --env or in neon.ts) overrides the injected credential, same as any other Neon-injected variable. See Environment variables. Because the credentials use AWS-standard names, the AWS SDK picks them up automatically when you don't override them. Only forcePathStyle needs explicit configuration:

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,
});

How branch binding works

Each credential is tied to the branch it was created on. It is valid for:

• That branch (the anchor branch)
• Any branch descended from it: preview branches, feature branches, CI branches

It's not valid for branches outside that lineage.

main  ──── credential valid here
  └── preview/feature-x  ──── and here
        └── preview/sub-branch  ──── and here
staging  ──── credential NOT valid here (different lineage)

Listing credentials

The Credentials page in the Console shows all credentials for the current branch: name, key ID, creation date, and last used time. To list via the API:

curl "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY"

This returns credential metadata. Secrets are never returned after creation.

Revoking credentials

To revoke from the Console, open the Credentials page and use the action menu (⋮) next to the credential. To revoke via the API:

curl -X DELETE "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials/{token_id}" \
  -H "Authorization: Bearer $NEON_API_KEY"

To rotate a credential, create a new one, update your environment variables, then revoke the old one.

Common errors