diff --git a/content/changelog/2024-12-13.md b/content/changelog/2024-12-13.md index 276d65140f..d2304b5d7f 100644 --- a/content/changelog/2024-12-13.md +++ b/content/changelog/2024-12-13.md @@ -13,6 +13,8 @@ We’ve added support for larger compute sizes: We now support per-project API keys, offering you finer-grained access control by limiting an API key's permissions to a particular project. This applies to organization-owned projects only — when creating an Organization API key, include the project ID in the request and the resulting key will be scoped to just that project. This key grants member-level permissions only, preventing destructive actions like deleting the project. +For more details, see [Create project-scoped API keys](/docs/manage/api-keys#create-project-scoped-organization-api-keys). + ## Introducing psql.sh: run psql directly in your browser We're excited to launch [psql.sh](https://psql.sh), a browser-based version of the PostgreSQL command-line client. This new tool lets you instantly spin up a fresh database and start running SQL queries and `psql` commands right in your browser. diff --git a/content/docs/manage/api-keys.md b/content/docs/manage/api-keys.md index d100a371b7..3df68f39fb 100644 --- a/content/docs/manage/api-keys.md +++ b/content/docs/manage/api-keys.md @@ -7,37 +7,149 @@ redirectFrom: updatedOn: '2024-12-04T16:09:42.523Z' --- -Most actions performed in the Neon Console can be performed using the [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Using the Neon API requires an API key. This topic describes how to generate, revoke, and use API keys. +Most actions performed in the Neon Console can also be performed using the [Neon API](https://api-docs.neon.tech/reference/getting-started-with-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. -API keys are global and belong to your Neon account. They can be used with any project that belongs to your Neon account. 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. +## Types of API keys -## Create an API key +Neon supports these types of API keys: -An API key (or token) is a randomly-generated 64-bit key that you must provide when calling Neon API methods. An API key remains valid until it is revoked. +- **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](/docs/manage/organizations#user-roles-and-permissions) to all projects within that organization. +- **Project-scoped organization API key** — These keys are scoped to a specific project within an organization. They provide [member-level access](/docs/manage/organizations#user-roles-and-permissions) to the specified project, and only that project. They cannot perform organization-related actions or destructive project operations like project deletion. -To generate an API key: +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. -1. Log in to the [Neon Console](https://console.neon.tech). -2. Click your account in the top right corner of the Neon Console, and select **Account settings**. -3. Select **API keys** and click **Create new API Key**. -4. Enter a name for the API key. -5. Click **Create** and copy the generated key. +## Creating API keys -Store your key in a safe location. You will not be able to view or copy the key again after leaving the **Account settings** page. You can safely store an API key in a locally installed credential manager or in a credential management service such as the [AWS Key Management Service](https://aws.amazon.com/kms/) or [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). If you lose an API key, revoke it and generate a new one. +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. -## Revoke an API key + +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. + -An API key that is no longer needed can be revoked. This action cannot be reversed. +### Create a personal API key -To revoke an API key: +You can create a personal API key in the Neon Console or using the Neon API. -1. Click your account in the top right corner of the Neon Console and select **Account settings**. -2. Select **API keys** to see a list of API keys. -3. To revoke a key, click **Revoke**. The key is immediately revoked. Any request that uses the key now fails. + + + +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](/docs/manage/personal_api_key.png) + + + +You'll need an existing personal key (create one from the Neon Console) in order to create new keys using the API. If you've got a key ready, you can use the following request to generate new keys: + +```bash shouldWrap +curl https://console.neon.tech/api/v2/api_keys + -H "Content-Type: application/json" + -H "Authorization: Bearer $PERSONAL_API_KEY" + -d '{"key_name": "my-key"}' +``` + +**Parameters:** + +- `key_name`: A descriptive name for the API key (e.g., "development", "staging", "ci-pipeline") + +**Response:** + +```json +{ + "id": 177630, + "key": "neon_api_key_1234567890abcdef1234567890abcdef" +} +``` + +To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createapikey). + + + + +### 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](/docs/manage/orgs-api#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](/docs/manage/org_api_keys.png) + + + + +To create an organization API key via the API, you need to use your personal API key. You also need to have admin-level permissions in the specified organization. + +```bash shouldWrap +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": "orgkey"}' +``` + +**Response:** + +```json +{ + "id": 165434, + "key": "neon_org_key_1234567890abcdef1234567890abcdef", + "name": "orgkey", + "created_at": "2022-11-15T20:13:35Z", + "created_by": "user_01h84bfr2npa81rn8h8jzz8mx4" +} +``` + + + + + +### 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](/docs/manage/organizations#user-roles-and-permissions), 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: + +```bash shouldWrap +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:** + +```json +{ + "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 `cURL` example uses the `/projects` endpoint to retrieve projects that belong to your Neon account. +The following example demonstrates how to use your API key to retrieve projects: ```bash curl 'https://console.neon.tech/api/v2/projects' \ @@ -80,103 +192,59 @@ where: Refer to the [Neon API reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api) for other supported Neon API methods. -## Manage API keys with the Neon API - -API key actions performed in the Neon Console can also be performed using the [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api). The following examples demonstrate how to create, view, and revoke API keys using the Neon API. - -### Prerequisites +## List API keys -You can create and manage API keys using the Neon API, but you need an API key to start with. You can obtain an API key from the Neon Console. For instructions, see [Create an API key](#create-an-api-key). In the examples shown below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request. + -The `jq` option specified in each example is an optional third-party tool that formats the JSON response, making it easier to read. For information about this utility, see [jq](https://stedolan.github.io/jq/). + +Navigate to **Account settings** > **API keys** to view your personal API keys, or your organization's **Settings** > **API keys** to view organization API keys. + -### Create an API key with the API + -The following Neon API method creates an API key. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createapikey). +For personal API keys: -```http -POST /api_keys -``` - -The API method appears as follows when specified in a cURL command. You must specify the `key_name` attribute and a name for the API key. - -```bash -curl https://console.neon.tech/api/v2/api_keys \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $NEON_API_KEY" \ - -d '{"key_name": "mynewkey"}' | jq +```bash shouldWrap +curl "https://console.neon.tech/api/v2/api_keys" \ + -H "Authorization: Bearer $NEON_API_KEY" \ + -H "Accept: application/json" | jq ``` -The response body includes an `id` for the key and a generated 64-bit `key` value, which can be used to access the Neon API. API keys should stored and managed securely, as they provide access to all objects in your Neon account. +For organization API keys: -
-Response body - -```json -{ - "id": 177630, - "key": "pgh66qptg0cdbzk9jmu4qpvn65jhvwkpfzc6qzi57z814ispmhfu7q4q85r44zv8" -} +```bash shouldWrap +curl "https://console.neon.tech/api/v2/organizations/{org_id}/api_keys" \ + -H "Authorization: Bearer $NEON_API_KEY" \ + -H "Accept: application/json" | jq ``` -
- -### List API keys with the API - -The following Neon API method lists API keys for your Neon account. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/listapikeys). + + -```http -GET /api_keys -``` +## Revoke API Keys -The API method appears as follows when specified in a cURL command. No parameters are required. - -```bash -curl "https://console.neon.tech/api/v2/api_keys" \ - -H "Authorization: Bearer $NEON_API_KEY" \ - -H "Accept: application/json" | jq -``` +You should revoke API keys that are no longer needed or if you suspect a key may have been compromised. Key details: -
-Response body +- 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 -```json -[ - { - "created_at": "2022-12-23T20:52:29Z", - "id": 177630, - "last_used_at": "2022-12-23T20:53:19Z", - "last_used_from_addr": "192.0.2.21", - "name": "mykey" - }, - { - "created_at": "2022-12-23T20:49:01Z", - "id": 177626, - "last_used_at": "2022-12-23T20:53:19Z", - "last_used_from_addr": "192.0.2.21", - "name": "sam_key" - }, - { - "created_at": "2022-12-23T20:48:31Z", - "id": 177624, - "last_used_at": "2022-12-23T20:53:19Z", - "last_used_from_addr": "192.0.2.21", - "name": "sally_key" - } -] -``` +### 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 -### Revoke an API key with the API + -The following Neon API method revokes the specified API key. The `key_id` is a required parameter. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/revokeapikey). + +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. -```http -DELETE /api_keys/{key_id} -``` +![Revoking an API key in the Neon Console](/docs/manage/revoke_api_key.png) + -The API method appears as follows when specified in a cURL command: + +The following Neon API method revokes the specified API key. The `key_id` is a required parameter: ```bash curl -X DELETE \ @@ -199,5 +267,9 @@ curl -X DELETE \ ``` + + + +To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createapikey). diff --git a/content/docs/manage/branches.md b/content/docs/manage/branches.md index d79675b620..413179ac39 100644 --- a/content/docs/manage/branches.md +++ b/content/docs/manage/branches.md @@ -231,6 +231,7 @@ The `jq` option specified in each example is an optional third-party tool that f A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](/docs/manage/api-keys#create-an-api-key). In the examples shown below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request. + ### Create a branch with the API The following Neon API method creates a branch. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createprojectbranch). diff --git a/content/docs/manage/databases.md b/content/docs/manage/databases.md index f18226d9b0..33974898cc 100644 --- a/content/docs/manage/databases.md +++ b/content/docs/manage/databases.md @@ -90,6 +90,7 @@ The `jq` option specified in each example is an optional third-party tool that f A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](/docs/manage/api-keys#create-an-api-key). In the cURL examples below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request. + ### Create a database with the API The following Neon API method creates a database. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createprojectbranchdatabase). diff --git a/content/docs/manage/endpoints.md b/content/docs/manage/endpoints.md index b874f9fc31..2ff10bf47b 100644 --- a/content/docs/manage/endpoints.md +++ b/content/docs/manage/endpoints.md @@ -266,6 +266,7 @@ The `jq` option specified in each example is an optional third-party tool that f A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](/docs/manage/api-keys#create-an-api-key). In the cURL examples below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request. + ### Create a compute with the API The following Neon API method creates a compute. diff --git a/content/docs/manage/orgs-api.md b/content/docs/manage/orgs-api.md index 43ddf71d13..30832038f8 100644 --- a/content/docs/manage/orgs-api.md +++ b/content/docs/manage/orgs-api.md @@ -41,9 +41,11 @@ To find your organization's `org_id`, navigate to your Organization's **Settings Only admins can create API keys for the organization. These keys provide admin-level access to all organization resources, including projects, members, and billing information. These are **user-independent** — they are not tied to a specific user. If any user leaves the organization, including the admin who created the API key, the API key remains active. -To create a new key, go to your organization’s settings and click the **Create new API key** button in the API keys section. +You can also create project-scoped organization API keys, which provide member-level access to a specific project within the organization. This allows for more granular access control when needed. -![creating an api key from the console](/docs/manage/org_api_keys.png) +Creating any type of API key (organization-wide or project-scoped) requires using a personal API key. Organization API keys cannot be used to create additional keys. + +For detailed instructions on creating and managing organization API keys, see [Manage API Keys](/docs/manage/api-keys#create-an-organization-api-key). ## Organization management actions diff --git a/content/docs/manage/projects.md b/content/docs/manage/projects.md index 696a2b867e..81ac057983 100644 --- a/content/docs/manage/projects.md +++ b/content/docs/manage/projects.md @@ -409,6 +409,8 @@ The `jq` option specified in each example is an optional third-party tool that f A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](/docs/manage/api-keys#create-an-api-key). In the cURL examples shown below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request. + + ### Create a project with the API The following Neon API method creates a project. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createproject). diff --git a/content/docs/manage/roles.md b/content/docs/manage/roles.md index e4fd8f388d..cb6647cd51 100644 --- a/content/docs/manage/roles.md +++ b/content/docs/manage/roles.md @@ -125,6 +125,7 @@ The `jq` option specified in each example is an optional third-party tool that f A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](/docs/manage/api-keys#create-an-api-key). In the cURL examples shown below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request. + ### Create a role with the API The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API reference](https://api-docs.neon.tech/reference/createprojectbranchrole). diff --git a/content/docs/shared-content/index.js b/content/docs/shared-content/index.js index 76857299ae..af7f0e95de 100644 --- a/content/docs/shared-content/index.js +++ b/content/docs/shared-content/index.js @@ -10,6 +10,7 @@ const sharedMdxComponents = { LRBeta: 'shared-content/lr-inbound-beta', FeatureBeta: 'shared-content/feature-beta', MigrationAssistant: 'shared-content/migration-assistant', + LinkAPIKey: 'shared-content/manage-api-keys', }; module.exports = sharedMdxComponents; diff --git a/content/docs/shared-content/manage-api-keys.md b/content/docs/shared-content/manage-api-keys.md new file mode 100644 index 0000000000..5779333205 --- /dev/null +++ b/content/docs/shared-content/manage-api-keys.md @@ -0,0 +1 @@ +To learn more about the types of API keys you can create — personal, organization, or project-scoped — see [Manage API Keys](/docs/manage/api-keys). diff --git a/public/docs/manage/personal_api_key.png b/public/docs/manage/personal_api_key.png new file mode 100644 index 0000000000..540c87f175 Binary files /dev/null and b/public/docs/manage/personal_api_key.png differ diff --git a/public/docs/manage/revoke_api_key.png b/public/docs/manage/revoke_api_key.png new file mode 100644 index 0000000000..faf3b4110c Binary files /dev/null and b/public/docs/manage/revoke_api_key.png differ