Neon Configuration#

Cartography needs a Neon API key with read access to the organizations you want to inventory.

Authentication#

Neon has two kinds of API key, and both work. See Manage API keys for how to create one.

Personal API key#

A personal API key acts as your user and can see every organization you belong to. Without --neon-org-ids, Cartography syncs all of them.

Organization API key#

An organization API key belongs to one organization, not to a user. Pass that organization’s ID with --neon-org-ids, because the endpoint that lists a user’s organizations answers an error to an organization key. A project-scoped organization key can read only its one project and is not suitable for a full inventory.

Required Permissions#

Access

Used for

Read projects, branches, and compute endpoints

Core inventory. Failures here stop the sync

Optional Permissions#

Access

Feature it enables

Organization members

NeonOrganizationMember nodes and the OWNED_BY edge from API keys

Organization API keys

NeonApiKey nodes

Branch roles and databases

NeonRole and NeonDatabase nodes

Object storage buckets (Beta)

NeonStorageBucket nodes

Branch credentials (Beta)

NeonCredential nodes

These listings answer 402, 403 or 404 when the key or plan cannot read them. Cartography then logs a warning, keeps whatever nodes an earlier sync stored, and skips their cleanup. A read failure is not proof that the resources were deleted.

If a branch’s object storage settings are unreadable, Cartography still loads that branch’s buckets without their endpoint fields, and skips bucket cleanup for the project.

Secret handling#

The module issues GET requests only and stores no secret material:

  • The role listing can include a role’s password. Each role record is built from an explicit field list, so the password never reaches the graph. Cartography never calls the reveal_password endpoint.

  • Organization API keys are listed by ID, name, and usage. The API never returns the token itself.

  • Branch credentials are listed by token ID, scopes, and usage. The listing never returns the API token or the S3 secret access key, and Cartography never calls the reveal endpoint.

  • Cartography never calls the connection URI endpoint.

Configure Cartography#

CLI option

Description

--neon-api-key-env-var

Name of the environment variable holding the Neon API key. Required to enable the module

--neon-org-ids

Comma-separated organization IDs (org-...) to sync. Required with an organization API key. Defaults to every organization a personal key’s user belongs to

--neon-base-url

Neon API base URL. Defaults to https://console.neon.tech/api/v2

Run Cartography#

export NEON_API_KEY="napi_..."
cartography \
  --neo4j-uri bolt://localhost:7687 \
  --selected-modules neon \
  --neon-api-key-env-var NEON_API_KEY

With an organization API key:

cartography \
  --neo4j-uri bolt://localhost:7687 \
  --selected-modules neon \
  --neon-api-key-env-var NEON_API_KEY \
  --neon-org-ids org-example-12345678

Troubleshooting#

  • The project listing is incomplete. When the API reports unavailable_project_ids, Cartography loads the projects it did receive and skips project cleanup for that organization, so no project is deleted from the graph because of a slow response.

  • Rate limits. The Neon API rate-limits requests per account. The module makes up to 5 requests per branch plus 2 per project, and retries 429 responses with exponential backoff.

References#