Manage API Keys (original) (raw)

Most actions performed in the Neon Console can also be performed using the Neon API. You'll need an API key to validate your requests. Each key is a randomly-generated 64-bit token that you must include when calling Neon API methods. All keys remain valid until deliberately revoked.

Neon supports three types of API keys:

Key Type	Who Can Create	Scope	Validity
Personal API Key	Any user	All organization projects where the user is a member	Valid until revoked; org project access ends if user leaves organization
Organization API Key	Organization administrators	All projects within the organization	Valid until revoked
Project-scoped API Key	Any organization member	Single specified project	Valid until revoked or project leaves organization

While there is no strict limit on the number of API keys you can create, we recommend keeping it under 10,000 per Neon account.

You'll need to create your first API key from the Neon Console, where you are already authenticated. You can then use that key to generate new keys from the API.

note

When creating API keys from the Neon Console, the secret token will be displayed only once. Copy it immediately and store it securely in a credential manager (like AWS Key Management Service or Azure Key Vault) — you won't be able to retrieve it later. If you lose an API key, you'll need to revoke it and create a new one.

You can create a personal API key in the Neon Console or using the Neon API.

In the Neon Console, select Account settings > API keys. You'll see a list of any existing keys, along with the button to create a new key.

Creating a personal API key in the Neon Console

Organization API keys provide admin-level access to all organization resources. Only organization admins can create these keys. To create an organization API key, you must use your personal API key and be an administrator in the organization. Neon will verify your admin status before allowing the key creation.

For more detail about organization-related methods, see Organization API Keys.

Navigate to your organization's Settings > API keys to view a list of existing keys and the button to create a new key.

creating an api key from the console

Project-scoped API keys have member-level access, meaning they cannot delete the project they are associated with. These keys:

Can only access and manage the specified project
Cannot perform organization-related actions or create new projects
Will stop working if the project is transferred out of the organization

In your organization's Settings > API keys, click Create new and select Project-scoped to create a key for your chosen project.

Project-scoped API keys from the Console

The following example demonstrates how to use your API key to retrieve projects:

curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq

where:

"https://console.neon.tech/api/v2/projects" is the resource URL, which includes the base URL for the Neon API and the /projects endpoint.
The "Accept: application/json" in the header specifies the accepted response type.
The Authorization: Bearer <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>N</mi><mi>E</mi><mi>O</mi><msub><mi>N</mi><mi>A</mi></msub><mi>P</mi><msub><mi>I</mi><mi>K</mi></msub><mi>E</mi><mi>Y</mi><mi mathvariant="normal">‘</mi><mi>e</mi><mi>n</mi><mi>t</mi><mi>r</mi><mi>y</mi><mi>i</mi><mi>n</mi><mi>t</mi><mi>h</mi><mi>e</mi><mi>h</mi><mi>e</mi><mi>a</mi><mi>d</mi><mi>e</mi><mi>r</mi><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>s</mi><mi>y</mi><mi>o</mi><mi>u</mi><mi>r</mi><mi>A</mi><mi>P</mi><mi>I</mi><mi>k</mi><mi>e</mi><mi>y</mi><mi mathvariant="normal">.</mi><mi>R</mi><mi>e</mi><mi>p</mi><mi>l</mi><mi>a</mi><mi>c</mi><mi>e</mi><mi mathvariant="normal">‘</mi></mrow><annotation encoding="application/x-tex">NEON_API_KEY entry in the header specifies your API key. Replace </annotation></semantics></math>NEONAPIKEY‘entryintheheaderspecifiesyourAPIkey.Replace‘NEON_API_KEY with an actual 64-bit API key. A request without this header, or containing an invalid or revoked API key, fails and returns a 401 Unauthorized HTTP status code.
jq is an optional third-party tool that formats the JSON response, making it easier to read. Response body

{
  "projects": [
    {
      "cpu_used_sec": 0,
      "id": "purple-shape-411361",
      "platform_id": "aws",
      "region_id": "aws-us-east-2",
      "name": "purple-shape-411361",
      "provisioner": "k8s-pod",
      "pg_version": 15,
      "locked": false,
      "created_at": "2023-01-03T18:22:56Z",
      "updated_at": "2023-01-03T18:22:56Z",
      "proxy_host": "us-east-2.aws.neon.tech",
      "branch_logical_size_limit": 3072
    }
  ]
}

Refer to the Neon API reference for other supported Neon API methods.

Navigate to Account settings > API keys to view your personal API keys, or your organization's Settings > API keys to view organization API keys.

You should revoke API keys that are no longer needed or if you suspect a key may have been compromised. Key details:

The action is immediate and permanent
All API requests using the revoked key will fail with a 401 Unauthorized error
The key cannot be reactivated — you'll need to create a new key if access is needed again
Personal API keys can only be revoked by the account owner
Organization API keys can be revoked by organization admins
Project-scoped keys can be revoked by organization admins

In the Neon Console, navigate to Account settings > API keys and click Revoke next to the key you want to revoke. The key will be immediately revoked. Any request that uses this key will now fail.

Revoking an API key in the Neon Console

Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more details, see Getting Support.

To view the API documentation for this method, refer to the Neon API reference.