Manage API Keys

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.

Types of API keys

Neon supports these types of API keys:

• Personal API key — These keys are tied to your individual Neon account. They can access your personal projects by default, and organization projects if you specify the organization ID in your API requests.
• Organization API key — These keys are scoped to a specific organization. They allow full admin-level access to all projects within that organization and don't require an org_id parameter. They cannot be used for personal projects.
• Project-scoped organization API key — These keys are scoped to a specific project within an organization. They provide member-level access to the specified project, and only that project. They cannot perform organization-related actions or destructive project operations like project deletion.

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.

Creating API keys

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.

Create a personal API key

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

Create an organization API key

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.

Create project-scoped organization API keys

Organization API keys can be scoped to individual projects within that organization. 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 their specified project
• Cannot perform organization-related actions or create new projects
• Will lose access if the project is transferred out of the organization

To create an API key scoped to a specific project:

curl --request POST \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer $PERSONAL_API_KEY' \
     --data '{"key_name":"only-this-project", "project_id": "some-project-123"}'

Parameters:

• org_id: The ID of your organization
• key_name: A descriptive name for the API key
• project_id: The ID of the project to which the API key will be scoped

Example Response:

{
  "id": 1904821,
  "key": "neon_project_key_1234567890abcdef1234567890abcdef",
  "name": "test-project-scope",
  "created_at": "2024-12-11T21:34:58Z",
  "created_by": "user_01h84bfr2npa81rn8h8jzz8mx4",
  "project_id": "project-id-123"
}

Make an API call

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 $NEON_API_KEY entry in the header specifies your API key. 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.

{
  "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.

List API keys

Revoke 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

Who can revoke keys

• 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

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