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 |
|
Organization API keys |
|
Branch roles and databases |
|
Object storage buckets (Beta) |
|
Branch credentials (Beta) |
|
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_passwordendpoint.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
revealendpoint.Cartography never calls the connection URI endpoint.
Configure Cartography#
CLI option |
Description |
|---|---|
|
Name of the environment variable holding the Neon API key. Required to enable the module |
|
Comma-separated organization IDs ( |
|
Neon API base URL. Defaults to |
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
429responses with exponential backoff.