Integrations - Neon | Tidal Control

Tidal Control's Neon integration monitors your Neon Postgres organisation's security configuration for compliance purposes. It authenticates with a bearer token against the Neon API (https://console.neon.tech/api/v2).

What this integration monitors

Projects: IP allowlists, branch protection, connection pooling, auto-suspend, block-public-connections, logical replication and HIPAA settings
Security guarantees: Password storage, data anonymization, encryption, patching and backup
Neon Auth: Authentication configuration
Account API keys: Key hygiene for the account
Organization API keys: Key hygiene for the organisation
Organization members: MFA enforcement
VPC endpoints: Network isolation

Requirements

Super User role in Tidal Control
Neon account with access to your organisation settings
Your Neon Organization ID (always required; see below)

Warning

The Organization ID is required. Without it, organisation-level checks (member MFA, organisation API keys, VPC endpoints) cannot run, and a personal access token cannot even list projects. Always configure the Organization ID so every test evaluates real data instead of passing without checking anything.

Choosing a credential

Neon supports two token types, and they behave differently:

Token type	Where to create it	Scope
Organization API key (recommended)	Neon Console → Organisation → Settings → API keys	Bound to one organisation
Personal access token (PAT)	Neon Console → Account settings → API keys	Your user, across every organisation you belong to

Prefer an organisation API key for a shared, org-wide integration. A personal access token is tied to an individual and is unusable without an Organization ID anyway (Neon's GET /projects endpoint returns HTTP 400 "org_id is required" for a PAT). The account-level API-keys check only reflects real data when a PAT is used; with an organisation API key it is legitimately empty, because an organisation key cannot enumerate a person's personal keys.

Configuration step-by-step plan

We'll create a Neon API key, copy the Organization ID, then add the connection in Tidal Control.

Configuration steps:

Find your Organization ID
Create an API key
Configure the integration in Tidal Control

Step 1: Find your Organization ID

Log in to the Neon Console
Open your organisation settings
Copy the Organization ID. It looks like org-...

Step 2: Create an API key

Neon offers two kinds of key, and the organisation key is the one to prefer for a shared integration.

Recommended: Organization API key

In the Neon Console, go to your Organization → Settings → API keys
Create a new API key and give it a name, e.g. Tidal Control
Copy the key: it is shown only once

Alternative: Personal access token

Go to Account settings → API keys
Create a new key and copy it

Warning

Save the key immediately. Neon only shows the full key value once at creation. If you close the dialog without copying it, you will need to create a new key.

Step 3: Configure the integration in Tidal Control

Go to Settings → Integrations in Tidal Control
Click the plus icon next to Neon
Fill in the configuration:
- Name: A descriptive name, e.g. Neon
- API Key: The organisation API key or personal access token from step 2
- Organization ID: The org-... identifier from step 1
Click "Create" to save the integration

Configuration fields explained

The integration dialog asks for the following values:

Name:

A descriptive name for this connection
For example: Neon, Neon Production

API Key:

A Neon organisation API key (recommended) or personal access token
Created in step 2
Keep this value secure

Organization ID:

The unique identifier of your Neon organisation (org-...)
Found in step 1
Required: all tests need it to evaluate real data

How the configuration affects which tests run

With the Organization ID configured, all tests run correctly regardless of token type. The combinations behave as follows:

Configuration	Project tests	Org-level tests (MFA, org keys, VPC)	Account API-key test
PAT, no Org ID	❌ all error (`org_id is required`)	⚠️ no data	✅
API key, no Org ID	✅	⚠️ pass without checking anything	⚠️ pass without checking
PAT + Org ID	✅	✅	✅
API key + Org ID	✅	✅	⚠️ empty (an org key can't see personal account keys)

Warning

Why "no Organization ID" is dangerous, not just incomplete. When an organisation-level test has no data, an "all rows pass" check passes vacuously. It shows green while having verified nothing. An integration with only an API key and no Organization ID would report, for example, "All organisation members have MFA enabled" as passing even though zero members were ever fetched. That is a false compliance signal. Tidal Control therefore now fails these tests loudly ("This Neon account requires an Organization ID") instead of passing vacuously.

Verification

The integration is working when all of the following are true:

Settings → Integrations shows Neon under Configured Integrations
Neon tests are available in the Tests section
Test refresh delivers results without authentication errors, and organisation-level tests no longer report the "requires an Organization ID" message

Frequently asked questions

Which token type should I use? An organisation API key, for a shared integration. A personal access token is tied to an individual and requires an Organization ID to work at all.

Why is the account API-keys test empty with an organisation key? An organisation API key cannot enumerate a person's personal account keys. This is expected. That check only reflects real data when a personal access token is used.

Do I really need the Organization ID if I use an organisation API key? Yes. The organisation key resolves its org implicitly for projects, but the organisation-level checks (member MFA, organisation API keys, VPC endpoints) still need the Organization ID to run at all.

Common problems

Project tests error with org_id is required

You are using a personal access token without an Organization ID
Add the org-... Organization ID to the integration

Organisation-level tests report "This Neon account requires an Organization ID"

The Organization ID is missing. Add it so the checks evaluate real data

"API Key is required"

Make sure you pasted the key. It is only shown once at creation

Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.

Info

Gather support info: Note which browser you're using, exact error messages, and which steps you've already tried. This speeds up the solution considerably.