diff --git a/agent-resources/cli.mdx b/agent-resources/cli.mdx index 355c6d91..e80bcac4 100644 --- a/agent-resources/cli.mdx +++ b/agent-resources/cli.mdx @@ -20,7 +20,11 @@ npx skills add upstash/skills # Authentication -The CLI needs your account email and a developer API key. Grab one from the [Upstash Console under Account → API Keys](https://console.upstash.com/account/api), then set credentials using whichever method fits your workflow. +The CLI needs your account email and a Developer API key. If you don't have a key yet, [create an API Key](/devops/developer-api/introduction) first. Then set credentials using whichever method fits your workflow. + + + Read-only API keys work too. Read commands like `list`, `get` and `stats` succeed, while commands that change resources are rejected by the API. Use a read-only key when the CLI is driven by an agent or pipeline that only needs to read. + ## 1. Saved login (recommended) diff --git a/agent-resources/mcp.mdx b/agent-resources/mcp.mdx index 347ac4c1..9292a141 100644 --- a/agent-resources/mcp.mdx +++ b/agent-resources/mcp.mdx @@ -44,7 +44,7 @@ Find the GitHub repository [here](https://github.com/upstash/mcp-server). Before installing, grab your credentials: * **Email**: your Upstash account email -* **API Key**: create one at [Upstash Console → Account → API Keys](https://console.upstash.com/account/api) +* **API Key**: a Developer API key. If you don't have one, [create an API key](/devops/developer-api/introduction) first. Readonly API keys are supported. When the server starts with one, it automatically disables every tool that would modify state, such as creating databases, deleting backups, or retrying workflows. Your agent can still read and query your account, but it cannot make changes. diff --git a/devops/developer-api/authentication.mdx b/devops/developer-api/authentication.mdx index 85d0a072..0544a91c 100644 --- a/devops/developer-api/authentication.mdx +++ b/devops/developer-api/authentication.mdx @@ -17,3 +17,7 @@ curl https://api.upstash.com/v2/redis/databases -u EMAIL:API_KEY ``` Replace `EMAIL` and `API_KEY` with your email and API key. + +`EMAIL` is always your own account email, even when you use a +[team API key](/devops/developer-api/introduction#team-api-keys). Any member of +the team can authenticate with the team's key by passing their own email. diff --git a/devops/developer-api/introduction.mdx b/devops/developer-api/introduction.mdx index 1c234526..9dd4b7fe 100644 --- a/devops/developer-api/introduction.mdx +++ b/devops/developer-api/introduction.mdx @@ -2,10 +2,12 @@ title: Getting Started --- -Using Upstash API, you can develop applications that can create and manage -Upstash products and resources. You can automate everything that -you can do in the console. To use developer API, you need to create an API key -in the console. +Using the Upstash Developer API, you can create and manage Upstash products and +resources programmatically. Everything you can do in the console can be +automated. The [Upstash CLI](/agent-resources/cli) and the +[Upstash MCP server](/agent-resources/mcp) use the same API key. + +To use the Developer API, you need to create an API key in the console. @@ -15,28 +17,43 @@ The Developer API is only available to native Upstash accounts. Accounts created ### Create an API key -1. Log in to the console then in the left menu click the - `Account > Management API` link. +1. Log in to the console, click your profile icon at the top right corner and + select `Settings`. -2. Click the `Create API Key` button. + + + + +2. Switch to the [`Developer API`](https://console.upstash.com/account/api) tab + and click the `Create API Key` button. -3. Enter a name for your key. You can not use the same name for multiple keys. +3. Enter a name for your key, pick its permissions and expiration, then submit. + You cannot use the same name for multiple keys. +A `Read/Write` key can use every API endpoint. A `Read Only` key can list and +inspect your resources but cannot change them, which makes it a good fit for +monitoring scripts and AI agents. Read-only keys are marked with a `Read Only` +tag in the key list. + +Keys can expire after 7, 30 or 90 days, on a custom date, or never. Choose an +expiring key when you can. The console warns you when a key expires within a +week, and an expired key stops working until you replace it with a new one. + -You need to download or copy/save your API key. Upstash does not remember or -keep your API for security reasons. So if you forget your API key, it becomes -useless; you need to create a new one. +You need to copy or download your API key. Upstash does not store or +show your API key again for security reasons. So if you lose your API key, it +becomes useless; you need to create a new one.
@@ -45,15 +62,42 @@ different applications. By default one user can create up to 37 API keys. If you need more than that, please send us an email at [support@upstash.com](mailto:support@upstash.com) -### Deleting an API key +### Team API keys -When an API key is exposed (e.g. accidentally shared in a public repository) or -not being used anymore; you should delete it. You can delete the API keys in -`Account > API Keys` screen. +An API key belongs to the account it was created in. If you switch the console +to a team and create a key there, the key belongs to that team and operates on +the team's resources. -### Roadmap +Authentication works the same way: pass your own account email as the +username, not the team id. Every member of the team can use the same team key, +each with their own email. + + -**Role based access:** You will be able to create API keys with specific -privileges. For example you will be able to create a key with read-only access. +Members with the `Readonly` team role can only perform read operations through +the API, even when using a `Read/Write` team key. -**Stats:** We will provide reports based on usage of your API keys. + + +### Using your API key + +The API uses HTTP Basic authentication: pass your account email as the +username and the API key as the password. See +[Authentication](/devops/developer-api/authentication) for details. + +```bash +curl https://api.upstash.com/v2/redis/databases -u EMAIL:API_KEY +``` + +The same credentials work with the [Upstash CLI](/agent-resources/cli), which +manages your resources from the terminal or CI/CD pipelines, and with the +[Upstash MCP server](/agent-resources/mcp), which lets AI agents manage and +debug your resources. When the MCP server starts with a read-only key, it +disables every tool that would modify state. + +### Deleting an API key + +When an API key is exposed (e.g. accidentally shared in a public repository) or +not being used anymore, you should delete it. You can delete API keys on the +same [`Personal Settings > Developer API`](https://console.upstash.com/account/api) +page. diff --git a/img/developerapi/api-key-create.png b/img/developerapi/api-key-create.png index 74dcefe4..0441f417 100644 Binary files a/img/developerapi/api-key-create.png and b/img/developerapi/api-key-create.png differ diff --git a/img/developerapi/api-key-list.png b/img/developerapi/api-key-list.png index 9709b8e2..17a20f05 100644 Binary files a/img/developerapi/api-key-list.png and b/img/developerapi/api-key-list.png differ diff --git a/img/developerapi/api-key-secret.png b/img/developerapi/api-key-secret.png index 0da181f4..b4a744a0 100644 Binary files a/img/developerapi/api-key-secret.png and b/img/developerapi/api-key-secret.png differ diff --git a/img/developerapi/profile-menu.png b/img/developerapi/profile-menu.png new file mode 100644 index 00000000..7eb16d3c Binary files /dev/null and b/img/developerapi/profile-menu.png differ diff --git a/llms-full.txt b/llms-full.txt index 3de69788..9bddeabb 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -66,7 +66,11 @@ npx skills add upstash/skills # Authentication -The CLI needs your account email and a developer API key. Grab one from the [Upstash Console under Account → API Keys](https://console.upstash.com/account/api), then set credentials using whichever method fits your workflow. +The CLI needs your account email and a Developer API key. If you don't have a key yet, [create an API Key](/docs/devops/developer-api/introduction) first. Then set credentials using whichever method fits your workflow. + + + Read-only API keys work too. Read commands like `list`, `get` and `stats` succeed, while commands that change resources are rejected by the API. Use a read-only key when the CLI is driven by an agent or pipeline that only needs to read. + ## 1. Saved login (recommended) @@ -309,7 +313,7 @@ Find the GitHub repository [here](https://github.com/upstash/mcp-server). Before installing, grab your credentials: * **Email**: your Upstash account email -* **API Key**: create one at [Upstash Console → Account → API Keys](https://console.upstash.com/account/api) +* **API Key**: a Developer API key. If you don't have one, [create an API key](/docs/devops/developer-api/introduction) first. Readonly API keys are supported. When the server starts with one, it automatically disables every tool that would modify state, such as creating databases, deleting backups, or retrying workflows. Your agent can still read and query your account, but it cannot make changes. @@ -7502,6 +7506,10 @@ curl https://api.upstash.com/v2/redis/databases -u EMAIL:API_KEY Replace `EMAIL` and `API_KEY` with your email and API key. +`EMAIL` is always your own account email, even when you use a +[team API key](/docs/devops/developer-api/introduction#team-api-keys). Any member of +the team can authenticate with the team's key by passing their own email. + # HTTP Status Codes Source: https://upstash.com/docs/devops/developer-api/http_status_codes @@ -7521,10 +7529,12 @@ Source: https://upstash.com/docs/devops/developer-api/http_status_codes # Getting Started Source: https://upstash.com/docs/devops/developer-api/introduction -Using Upstash API, you can develop applications that can create and manage -Upstash products and resources. You can automate everything that -you can do in the console. To use developer API, you need to create an API key -in the console. +Using the Upstash Developer API, you can create and manage Upstash products and +resources programmatically. Everything you can do in the console can be +automated. The [Upstash CLI](/docs/agent-resources/cli) and the +[Upstash MCP server](/docs/agent-resources/mcp) use the same API key. + +To use the Developer API, you need to create an API key in the console. @@ -7534,22 +7544,35 @@ The Developer API is only available to native Upstash accounts. Accounts created ### Create an API key -1. Log in to the console then in the left menu click the - `Account > Management API` link. +1. Log in to the console, click your profile icon at the top right corner and + select `Settings`. + + -2. Click the `Create API Key` button. +2. Switch to the [`Developer API`](https://console.upstash.com/account/api) tab + and click the `Create API Key` button. -3. Enter a name for your key. You can not use the same name for multiple keys. +3. Enter a name for your key, pick its permissions and expiration, then submit. + You cannot use the same name for multiple keys. +A `Read/Write` key can use every API endpoint. A `Read Only` key can list and +inspect your resources but cannot change them, which makes it a good fit for +monitoring scripts and AI agents. Read-only keys are marked with a `Read Only` +tag in the key list. + +Keys can expire after 7, 30 or 90 days, on a custom date, or never. Choose an +expiring key when you can. The console warns you when a key expires within a +week, and an expired key stops working until you replace it with a new one. + -You need to download or copy/save your API key. Upstash does not remember or -keep your API for security reasons. So if you forget your API key, it becomes -useless; you need to create a new one. +You need to copy or download your API key. Upstash does not store or +show your API key again for security reasons. So if you lose your API key, it +becomes useless; you need to create a new one.
@@ -7558,18 +7581,45 @@ different applications. By default one user can create up to 37 API keys. If you need more than that, please send us an email at [support@upstash.com](mailto:support@upstash.com) -### Deleting an API key +### Team API keys -When an API key is exposed (e.g. accidentally shared in a public repository) or -not being used anymore; you should delete it. You can delete the API keys in -`Account > API Keys` screen. +An API key belongs to the account it was created in. If you switch the console +to a team and create a key there, the key belongs to that team and operates on +the team's resources. -### Roadmap +Authentication works the same way: pass your own account email as the +username, not the team id. Every member of the team can use the same team key, +each with their own email. -**Role based access:** You will be able to create API keys with specific -privileges. For example you will be able to create a key with read-only access. + + +Members with the `Readonly` team role can only perform read operations through +the API, even when using a `Read/Write` team key. + + + +### Using your API key + +The API uses HTTP Basic authentication: pass your account email as the +username and the API key as the password. See +[Authentication](/docs/devops/developer-api/authentication) for details. + +```bash +curl https://api.upstash.com/v2/redis/databases -u EMAIL:API_KEY +``` + +The same credentials work with the [Upstash CLI](/docs/agent-resources/cli), which +manages your resources from the terminal or CI/CD pipelines, and with the +[Upstash MCP server](/docs/agent-resources/mcp), which lets AI agents manage and +debug your resources. When the MCP server starts with a read-only key, it +disables every tool that would modify state. -**Stats:** We will provide reports based on usage of your API keys. +### Deleting an API key + +When an API key is exposed (e.g. accidentally shared in a public repository) or +not being used anymore, you should delete it. You can delete API keys on the +same [`Personal Settings > Developer API`](https://console.upstash.com/account/api) +page. # Create Backup Source: https://upstash.com/docs/devops/developer-api/redis/backup/create_backup