# Credentials

import Screenshot from "@docs/Screenshot.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

A credential is an account connection or secret Ren uses to access a service, like a Gmail connection, a Stripe API key, or a `DATABASE_URL` used by scripts. Ren stores each credential encrypted and passes it to the tools that need it. Neither you nor Ren sees the raw value again after you save it.

In the API and CLI, credentials live in vaults: `credential` and `vault`.

## Where credentials live

Every credential belongs to one of three levels. Pick the level by who should be able to use it.

| Level        | Who can use it                                               | Use it for                                           |
| ------------ | ------------------------------------------------------------ | ---------------------------------------------------- |
| Organization | Every chat in the organization                               | Accounts shared across spaces, like a company Notion |
| Space        | Chats in that space's projects, and members' personal spaces | One team's or one client's accounts                  |
| Personal     | Only chats in your personal space                            | Your own accounts, like your inbox                   |

For an agency, store each client's accounts in that client's space, so only its members can use them.

A space's credentials are visible only to its members. There's no admin override: an organization admin who isn't a member of a space can't see or use its credentials. Your personal credentials are visible only to you. Organization admins can't access personal credentials.

<SurfaceTabs>
<Fragment slot="app">

Open **Settings → Credentials** to see every credential you can use, with its level. Filter by level to narrow the list.

<Screenshot
  shot="credentials/settings"
  alt="Settings Credentials listing credentials from the organization, a space, and Personal, with the scope filter open"
/>

</Fragment>
<Fragment slot="cli">

```sh
ren vaults list
ren credentials list <vault-id>
```

`ren vaults list` shows the vault for each level.

</Fragment>
</SurfaceTabs>

### Which credential Ren uses

Ren uses the first matching credential in this order:

- **In a shared space:** the space's credential, then the organization's.
- **In your personal space:** your personal credential, then credentials from the shared spaces you belong to (oldest space first), then the organization's.

Channel, scheduled, and task chats use the credential lookup order for their project's space. The sender's identity doesn't change that order.

## Types of credentials

**Settings → Credentials** groups credentials by type:

| Type       | What it holds                                                              | How you add it                                                             |
| ---------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| App        | A signed-in account, like Gmail or GitHub                                  | Sign in when you [connect an app](/docs/concepts/apps/#connect-an-account) |
| Token      | An API token for an app or custom MCP                                      | Paste it when you connect the app or custom MCP                            |
| Password   | A username and password                                                    | Enter them when you connect the app or custom MCP                          |
| Secret     | A value Ren reads as an environment variable, like `$API_KEY`              | **Add credential** on the Credentials page                                 |
| Custom MCP | The connection fields a [custom MCP](/docs/concepts/custom-mcps/) asks for | Fill them in when you connect the custom MCP                               |

Each level holds at most 100 credentials, and one credential per app, custom MCP, or secret name. Saving a new one for the same app replaces the old one.

## Add a credential

Add a secret, like an API key a skill reads from the environment. To sign in to an app, see [Sign in to an app](#sign-in-to-an-app).

<SurfaceTabs>
<Fragment slot="app">

1. Open **Settings → Credentials** and select **Add credential**.
2. Choose where it lives: your organization or a space. Pick your personal space to keep it to yourself.
3. Enter a **Name** in `UPPER_SNAKE_CASE`, like `STRIPE_API_KEY`, and its **Value**.
4. Select **Store**.

The credential appears in the list with its level.

<Screenshot
  shot="credentials/add"
  frame="detail"
  alt="The New credential drawer with the organization level, an UPPER_SNAKE_CASE name, and a masked value"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Store my OpenWeather API key as OPENWEATHER_API_KEY for this space." />

Ren asks for the value or points you to where to enter it.

</Fragment>
<Fragment slot="cli">

```sh
ren vaults list
printf %s "$STRIPE_KEY" | ren credentials create <vault-id> --auth-type env --label STRIPE_API_KEY --value-stdin
```

`ren vaults list` shows the vault for each level. Run `ren credentials create --help` for the other types.

</Fragment>
</SurfaceTabs>

## Sign in to an app

OAuth connects apps and custom MCPs through the provider's sign-in page. Ren saves the connection in the project's space, or in your personal credentials when you're in your personal space.

<SurfaceTabs>
<Fragment slot="app">

1. Ask Ren to use the app in a chat, or open the app in **Marketplace → Apps** and add it to a project.
2. Select **Connect** on the card, then sign in to the account you want Ren to use.
3. Return to Ren. The card shows **Connected**.

If the account is already connected in another space you belong to, the card offers **Reuse** to copy it into this space, or **Add new** to sign in again.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Connect my Google Calendar." />

Select **Connect** on the card Ren shows and finish signing in. Connect cards only work in the web app.

</Fragment>
<Fragment slot="cli">

```sh
ren credentials connect <mcp> --vault-id <vault-id>
```

</Fragment>
</SurfaceTabs>

## Edit, move, or delete a credential

Deleting is permanent: chats that use the credential fail at the step that needs it until you add a replacement.

You can't view a credential's value after you save it. Ren shows the last four characters of a secret, or **Connected** for a signed-in account. To change a value, select **Update value**.

<SurfaceTabs>
<Fragment slot="app">

1. Open **Settings → Credentials** and find the credential.
2. Open its menu and choose:
   - **Rename** to change its display name.
   - **Update value** to replace a secret, or **Reconnect** to sign in to the account again.
   - **Transfer** to copy or move it to another level.
   - **Delete** to remove it.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Move the STRIPE_API_KEY credential from my personal credentials to the Billing space." />

</Fragment>
<Fragment slot="cli">

```sh
ren credentials update <vault-id> <credential-id> --name "Stripe live key"
ren credentials transfer <vault-id> <credential-id> --target-vault-id <vault-id> --mode move
ren credentials delete <vault-id> <credential-id>
```

</Fragment>
</SurfaceTabs>