Getting started with Neon Data API

\1. Navigate to the Data API page

In the Neon Console, select your project and select Postgres database > Data API.

\2. Configure authentication

The Data API uses JWTs for access control. Configure a provider now or later from the Settings tab. For public data that doesn't require login, use the anonymous role instead.

• Managed Better Auth: Check the Use Managed Better Auth checkbox to enable Managed Better Auth as your provider. Managed Better Auth manages sign-up, login, and account access, issuing the JWTs required for API requests.
• Other providers: Leave the checkbox unchecked and configure your provider (such as Auth0, Clerk, or Firebase Auth) later. See Custom authentication providers for setup instructions.

\3. Configure schema access (optional)

The Grant public schema access checkbox automatically applies database permissions so the authenticated role can read and write to tables in the public schema.

-- Schema usage
GRANT USAGE ON SCHEMA public TO authenticated;

-- For existing tables
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO authenticated;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT, UPDATE, INSERT, DELETE ON TABLES TO authenticated;

-- For sequences (for identity columns)
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO authenticated;

Enable this checkbox unless you need to manage permissions manually. If you leave it unchecked, see Access control for details on granting permissions yourself.

\4. Enable Data API

Click Enable Data API to activate the Data API. Once enabled, you'll see the Data API page.

On the API tab, you'll see:

• API URL: Your REST API endpoint for accessing your database
• Refresh schema cache: A button to update the Data API when you make schema changes
• Security section: Options to configure authentication and enable Row-Level Security on your tables

For advanced configuration options like custom authentication providers, exposed schemas, and CORS settings, see the Settings tab or refer to Managing the Data API.

Next, you'll create a table with Row-Level Security (RLS) policies to define which rows users can access.

The Data API interacts directly with your Postgres schema. Because the API is accessible over the internet, it's crucial to enforce security at the database level using PostgreSQL's Row-Level Security (RLS) features.

In this example, we'll create a posts table where users can read published posts and manage their own posts securely. Choose the approach that matches how you manage your database schema:

• SQL: Write SQL directly in the Neon SQL Editor or manage migrations manually. See our PostgreSQL RLS tutorial for more on RLS fundamentals.
• Drizzle (crudPolicy): A high-level helper that generates RLS policies in one declaration. Best for simple cases where read and modify permissions follow the same pattern.
• Drizzle (pgPolicy): Define policies per operation or use a single FOR ALL policy. Use this when you need different logic for different operations (for example, time-limited updates, different rules for INSERT vs UPDATE).

For more on Drizzle RLS, see our Drizzle RLS guide.

-- This script creates a posts table, enables RLS, and defines two policies:
-- one allows authenticated users to read published posts, and the other
-- gives users full access (read, insert, update, delete) to their own posts.

-- 1. Create the table
CREATE TABLE posts (
  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  user_id text DEFAULT (auth.user_id()) NOT NULL,
  content text NOT NULL,
  is_published boolean DEFAULT false,
  "created_at" timestamp with time zone DEFAULT now() NOT NULL
);

-- 2. Enable RLS
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- 3. Read published posts
CREATE POLICY read_published_posts ON posts
FOR SELECT TO authenticated
USING (is_published = true);

-- 4. Full access to own posts
CREATE POLICY manage_own_posts ON posts
FOR ALL TO authenticated
USING (auth.user_id() = user_id)
WITH CHECK (auth.user_id() = user_id);

// This schema defines the same two-policy behavior using Drizzle ORM. The crudPolicy
// helper generates equivalent RLS: `read` allows published posts or own posts,
// and `modify` restricts insert, update, and delete to own posts.

import { sql } from 'drizzle-orm';
import { crudPolicy, authenticatedRole, authUid } from 'drizzle-orm/neon';
import { bigint, boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const posts = pgTable(
  'posts',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    content: text().notNull(),
    isPublished: boolean('is_published').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    crudPolicy({
      role: authenticatedRole,
      read: sql`is_published OR (auth.user_id() = ${table.userId})`,
      modify: authUid(table.userId),
    }),
  ]
);

// This schema defines the same two-policy behavior using Drizzle ORM with pgPolicy.
// One policy allows reading published posts; the other gives full access to own posts.

import { sql } from 'drizzle-orm';
import { authenticatedRole, authUid } from 'drizzle-orm/neon';
import { bigint, boolean, pgPolicy, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const posts = pgTable(
  'posts',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    content: text().notNull(),
    isPublished: boolean('is_published').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    pgPolicy('read_published_posts', {
      to: authenticatedRole,
      for: 'select',
      using: sql`is_published = true`,
    }),
    pgPolicy('manage_own_posts', {
      to: authenticatedRole,
      for: 'all',
      using: authUid(table.userId),
      withCheck: authUid(table.userId),
    }),
  ]
);

The Data API caches your database schema for performance. When you modify your schema (adding tables, modifying columns, or changing structure, etc.), you need to refresh this cache for the changes to take effect.

Option 1: Neon Console

Go to Postgres database > Data API in the Neon Console and click Refresh schema cache.

Option 2: Neon API

You can also refresh the schema cache programmatically. The PATCH /projects/{project_id}/branches/{branch_id}/data-api/{database_name} endpoint always refreshes the schema cache as part of the operation. Send an empty body to trigger a refresh:

curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/data-api/{database_name}' \
  -H 'Authorization: Bearer YOUR_NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

You can connect to the Data API using a client library or direct HTTP requests.

Option 1: Using a client library

Install a client library and run your first query. Choose the option that matches your authentication provider:

npm install @neondatabase/neon-js

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

// Initialize with Managed Better Auth
// Use your Neon database URL without credentials or query parameters.
// Example: https://ep-example.c-2.us-east-1.aws.neon.tech/neondb
const client = createClient(import.meta.env.VITE_NEON_DATABASE_URL);

// Query - the JWT token is injected automatically when the user is signed in
const { data, error } = await client
  .from('posts')
  .select('*')
  .eq('is_published', true)
  .order('created_at', { ascending: false });

console.log(data);

npm install @neondatabase/postgrest-js

import { fetchWithToken, NeonPostgrestClient } from '@neondatabase/postgrest-js';

const getTokenFromAuthSystem = async (): Promise<string> => {
  // Retrieve the JWT token from your auth system (e.g., Auth0, Clerk, Firebase)
  return 'your-jwt-token';
};

// Get your URL from the Neon Console or run: neon data-api get
const client = new NeonPostgrestClient({
  dataApiUrl: import.meta.env.VITE_NEON_DATA_API_URL,
  options: {
    global: {
      fetch: fetchWithToken(getTokenFromAuthSystem),
    },
  },
});

// Query
const { data, error } = await client
  .from('posts')
  .select('*')
  .eq('is_published', true)
  .order('created_at', { ascending: false });

console.log(data);

For detailed guidance on performing INSERT, UPDATE, DELETE, and advanced queries (filters, joins, stored procedures, etc.) in either case, refer to the Neon Javascript SDK documentation.

Option 2: Direct HTTP requests

Query the Data API directly using any HTTP client. Include the Authorization header with a valid JWT token from your authentication provider. The token must include a sub claim for RLS policies to work correctly.

Where to get the JWT token:

• Your auth provider's SDK: Retrieve the token using your provider's API (for example, getAccessToken() in Auth0, getToken() in Clerk).
• Managed Better Auth: Retrieve the token using client.auth.getSession() from the @neondatabase/neon-js library (see Get current session), or use the Auth API reference UI for manual testing (see Testing with Managed Better Auth below).

About the sub claim:

For RLS policies to work correctly, the JWT token must include a sub (subject) claim, which contains the user's unique identifier. The Data API uses this claim to enforce Row-Level Security policies via the auth.user_id() function. Most authentication providers include this claim by default.

Example: SELECT (GET)

This request queries the posts table for all published posts, ordered by most recent first:

curl -X GET 'https://your-data-api-endpoint/rest/v1/posts?is_published=eq.true&order=created_at.desc' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json'

Example: INSERT (POST)

This request inserts a new row into the posts table, setting the content column:

curl -X POST 'https://your-data-api-endpoint/rest/v1/posts' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Hello world"}'

For UPDATE, DELETE, filtering, and other operations, see the PostgREST documentation.