# Connect Upstash Redis

An account of Upstash Redis is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Serverless Redis plane — databases through the Management API, key-value data through each database REST endpoint.

One account is one Upstash account (email and management API key); one resource is one Redis database. Its owner labels each database with an environment; key reads and writes, deletions, FLUSH, arbitrary commands and database management are separate permissions held per label.

Permissions, presets and tools of this service: [Upstash Redis plugin](/plugins/upstash-redis).

## How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (`providers.<id>.*`, see [configuration keys](/docs/configuration/keys)). Every instance registers its own app: this gateway never uses an app shared with another one.

### The usual way: with a key pasted by hand

Where: [https://console.upstash.com/account/api](https://console.upstash.com/account/api)

What the connect page asks:

- Account email: The email of the Upstash account (or team member) that owns the API key. Sent as the Basic auth user name.
- Management API key (secret): Create a key in the Upstash console → Account → Management API. The key does not expire; revoke it in the console to end what this account can do.

## Disconnecting

Delete the management API key in the Upstash console, under Account, Management API.

## Registration notes from the plugin

From the plugin's [README](https://github.com/vaubaan/gateway/blob/main/plugins/upstash-redis/README.md), written for the people who register the app or create the token.

### Credential

`api-key` with two fields, collected by the host's generic form:

| Field     | Secret | Value                                                                                   |
| --------- | ------ | --------------------------------------------------------------------------------------- |
| `email`   | no     | The email of the Upstash account (or team member) owning the key. Basic auth user name. |
| `api_key` | yes    | A Management API key (Upstash console → Account → Management API). Basic auth password. |

There is no OAuth app to register: the Upstash Developer API is reached with
HTTP Basic auth (`email:api_key`). The key does not expire (`refresh` is absent); revoke it in
the console to end the connection.

The per-database REST tokens (Data API) are **not** part of the credential:
`execute` reads them from `GET /v2/redis/database/{id}` at call time and
never returns them — Management API answers are redacted of `rest_token`,
`read_only_rest_token` and `password` before reaching the agent. The token
is posted to `https://<label>.upstash.io` only: the endpoint the Management
API names (`rest_url`, or `endpoint`) is reduced to its label and rebuilt
(`restEndpointOf`), and a database answer naming any other host, scheme,
port or path makes the call fail before anything is sent. A connection
made of per-database REST tokens was considered and rejected: it could
neither discover its databases nor reach the management tools.

What `execute` declines itself (a database outside the mission, a malformed
argument, a pipeline-shaped `command`) is an `isError` result; a provider
failure is thrown.