# AI Gateway authentication

How Neon credentials work with AI Gateway

AI Gateway uses Neon bearer credentials, the same scoped-credential system as [Object Storage](/guides/object-storage-authentication): one credential API mints branch-scoped tokens that differ by scope (AI Gateway uses `ai_gateway:invoke`). No provider API keys are needed.

## Creating a credential

A credential must include the `ai_gateway:invoke` scope.

**CLI**

Create a credential with the [Neon CLI](/guides/apis-sdks-cli-credentials):

```bash
neon credentials create --scope ai_gateway:invoke --name my-app-credential
```

The `api_token` is printed once; set it as `NEON_AI_GATEWAY_TOKEN`. Run it in a directory [linked](/guides/apis-sdks-cli-link) to your project, or pass `--project-id` and `--branch`.

**Console**

In the Neon Console, click **Connect** at the top of the sidebar and open the **AI Gateway** tab. The snippet includes both gateway env vars (see [Environment variables](/guides/ai-gateway-authentication#environment-variables) below). Click **Reveal credential** to show the token, or **Copy snippet** to copy the full `.env`. Use **Rotate credential** to replace the token in place.

The Connect dialog reveals and rotates the current credential. To list all credentials for the branch or revoke one, use the [Neon CLI](/guides/apis-sdks-cli-credentials) or the API (below).

**API**

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["ai_gateway:invoke"], "principal_type": "user"}'
```

The response includes an `api_token` field. Store it as an environment variable:

```bash
export NEON_AI_GATEWAY_TOKEN=nt_live_...
```

## Pull credentials with neon

For local development, `neon env pull` writes your AI Gateway credentials to your `.env` file automatically, with no manual copy-paste from the API response:

```bash
neon env pull --file .env
```

This populates `NEON_AI_GATEWAY_TOKEN` and `NEON_AI_GATEWAY_BASE_URL` for the current branch alongside your database connection string. Running `neon config apply` or `neon deploy` also auto-pulls credentials after a successful apply. To check current credential status:

```bash
neon config status
```

For production deployments, use the [API-based workflow](/guides/ai-gateway-authentication#creating-a-credential) to create named credentials. `expires_at` is accepted but not currently enforced. Revoke credentials explicitly instead of relying on expiry.

## Using your credential

Pass your credential as a bearer token on every request:

```
Authorization: Bearer <your-credential>
```

When using an AI SDK, set this as the `apiKey` parameter:

**TypeScript**

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});
```

**Python**

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)
```

## Environment variables

Neon provides two gateway env vars. `NEON_AI_GATEWAY_BASE_URL` is the bare branch host, so you append the dialect path yourself when configuring an SDK.

| Variable                   | Value                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `NEON_AI_GATEWAY_TOKEN`    | Bearer token (`nt_live_...`)                                                              |
| `NEON_AI_GATEWAY_BASE_URL` | Bare branch host: `https://<branch-host>`, with no path. Append the dialect path yourself |

Append the dialect path for the endpoint you need:

```
NEON_AI_GATEWAY_BASE_URL + /v1            → chat completions (all providers)
NEON_AI_GATEWAY_BASE_URL + /openai/v1     → OpenAI Responses API
NEON_AI_GATEWAY_BASE_URL + /gemini        → Gemini generateContent API
```

The Gemini value is an SDK base URL: google-genai appends `/v1beta/models/...`, so don't add that segment yourself. Calling the endpoint directly takes the full path, `/gemini/v1beta/models/<model>:<action>`.

Each inference dialect is also reachable at a longer `/ai-gateway/<dialect>/v1` path (e.g. `/ai-gateway/mlflow/v1` for chat completions, `/ai-gateway/openai/v1` for Responses, `/ai-gateway/gemini` for Gemini). Both forms behave identically and neither is deprecated, but the shorter paths are what the docs and SDKs use. The model list is the exception: it has only `GET /v1/models`, with no `/ai-gateway/...` form. See [Shorter paths](/guides/ai-gateway-models#shorter-paths) for the full mapping.

To use an OpenAI SDK, set its `apiKey` and `baseURL` from these variables (see the examples below).

## Credentials in Neon Functions

When your code runs inside Neon Functions, both gateway env vars are injected automatically. No credential creation step required:

| Variable                   | Value                                               |
| -------------------------- | --------------------------------------------------- |
| `NEON_AI_GATEWAY_TOKEN`    | Bearer token for the AI Gateway                     |
| `NEON_AI_GATEWAY_BASE_URL` | Branch gateway host with `https://` prefix, no path |

See [Environment variables](/guides/neon-functions-environment-variables) for the full list of variables Neon injects into a function.

Configure an OpenAI SDK by setting `apiKey` and `baseURL` from these variables. Use the OpenAI Responses dialect for `responses.create()`:

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: 'gpt-5-mini',
  input: 'What is Neon?',
});
```

For the chat completions endpoint, point the base URL at `/v1` instead:

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});
```

## How branch binding works

Each credential is tied to the branch it was created on. It's 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.

This means a credential created on your `main` branch works in all branches that were forked from `main`. A credential created on a feature branch only works within that feature branch's descendants.

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

This design lets you use a single credential across your entire development workflow (local dev, preview deployments, and CI) without creating separate credentials for each environment.

## Common auth errors

| Error                     | Cause                                      | Fix                                                                                                                             |
| ------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`        | Missing or invalid credential              | Check that `NEON_AI_GATEWAY_TOKEN` is set and contains the full token                                                           |
| `403 Forbidden`           | Credential lacks `ai_gateway:invoke` scope | Recreate the credential with the correct scope                                                                                  |
| `403 Forbidden`           | Branch not in credential lineage           | Use a credential created on this branch or an ancestor branch. The gateway returns: `credential not authorized for this branch` |
| `503 Service Unavailable` | Auth store temporarily unavailable         | Retry the request                                                                                                               |

## Rotating credentials

To rotate a credential in place with the [Neon CLI](/guides/apis-sdks-cli-credentials), run `neon credentials rotate <token_id>` (find the id with `neon credentials list`). The `token_id` stays the same and a new `api_token` is minted, so update `NEON_AI_GATEWAY_TOKEN` with it. Otherwise, create a new credential, update your environment variables, then revoke the old one.

The Console's **Connect** dialog can rotate a credential (**AI Gateway** tab > **Rotate credential**) but not revoke one. To revoke, use the [Neon CLI](/guides/apis-sdks-cli-credentials) (`neon credentials revoke <token_id>`) or the API:

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

Or with the [Neon CLI](/guides/apis-sdks-cli-credentials):

```bash
neon credentials revoke <token_id>
```

## Related pages

- [AI Gateway troubleshooting](./ai-gateway-troubleshooting.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.