Add JWKS URL

POST /projects/{project_id}/jwks

Adds a JWKS URL to the specified project for verifying JWTs used as the authentication mechanism.

The URL must be a valid HTTPS URL that returns a JSON Web Key Set.

The provider_name field allows you to specify which authentication provider you're using (e.g., Clerk, Auth0, AWS Cognito).

The branch_id scopes the JWKS URL to specific branches; if not specified, it applies to all branches.

The role_names scopes the URL to specific roles; if not specified, default roles are used (authenticator, authenticated, anonymous).

The jwt_audience specifies which aud values are accepted in JWTs.

Markdown for AI context

curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/jwks" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"

Also available in

import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.addProjectJwks({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID
  }
});

Project ID

project_id

string

The Neon project ID

2 required Required: jwks_url, provider_name.

JWKS url

jwks_url

string

URL of the provider's JWKS endpoint used to verify JWTs.

Provider name

provider_name

string

The name of the authentication provider (e.g., Clerk, Stytch, Auth0)

Branch ID

branch_id

string

The Neon branch ID. Returned as id from GET /projects/{project_id}/branches.

JWT audience

jwt_audience

string

Expected aud claim in incoming JWTs. When set, tokens with a different audience are rejected; tokens with no audience are still accepted. Omit to skip audience validation.

Role namesdeprecated

role_names

array

Deprecated. The roles the JWKS should be mapped to. By default, the JWKS is mapped to the authenticator, authenticated, and anonymous roles.

Skip role creation

skip_role_creation

booleandefault: false

Deprecated. Only used with Neon RLS. If true, role creation is skipped.

201

The JWKS URL was added to the project's authentication connections

default

General error

This endpoint can return the standard Neon API error response.

Response fields

• message Required. Human-readable error message.
• code Required. Machine-readable error code.
• request_id Optional. Request identifier for debugging. You can provide one with the X-Request-ID header.

Retry guidance

If no response is returned, the request may still have reached the server. This is why retry safety depends on the method and status code.

Idempotent methods (GET, HEAD, OPTIONS) are generally safe to retry after a network error or timeout. Non-idempotent methods (POST, PATCH, DELETE, PUT) can change state, so avoid automatic retries unless your workflow can tolerate duplicate effects.

Responses with 423 Locked or 503 Service Unavailable are safe to retry. 423 Locked means the resource is temporarily locked, usually because another operation is in progress.