# Credential Vault

Store a secret once and reference it from tools, custom API sources, MCP servers, knowledge indexes, and connectors

The Credential Vault is a store of named secrets. You set a secret once and
reference it from every place that needs it: tools, custom API sources, MCP
servers, knowledge indexes, and tool connectors. A credential is **org-wide**, so
any tool can use it, or it belongs to one **department**, so only that
department's tools can use it. See [Department credentials](#department-credentials).

Vault credentials are **write-only**: you provide a value when you create a
credential, and you can replace it by rotating the value, but the value is never
displayed or returned again. Nothing in the dashboard reads a stored secret back.

## Where it lives

Open the Risotto dashboard and go to **Settings → Credential Vault**. The page
has three tabs:

- **Credentials** - the vault credentials you create, rotate, and reference. This
  is the only tab you edit.
- **Other credentials** - a read-only inventory of secrets still stored in an
  integration's own configuration instead of the vault. See [Other credentials
  and OAuth connections](#other-credentials-and-oauth-connections).
- **OAuth** - a read-only list of OAuth connections, shown for visibility.

Risotto API keys are not on this page. They are in **Settings → Developers → [API
keys](https://www.tryrisotto.com/docs/dashboard/settings/developers/api-keys)**.

Org Admins and Managers see all three tabs. A department Supervisor sees only the
**Credentials** tab, with the credentials described in [Who can manage the
vault](#who-can-manage-the-vault).

The **Credentials** tab lists each credential with these columns:

- **Name**, with the credential's description under it.
- **Type** - **Secret text** or **JSON document**.
- **Department** - the owning department, or **Org-wide**.
- **Allowed Hosts** - the hosts the value may be sent to, or **Any host**.
- **Used By** - the names of the tools, sources, servers, indexes, and connections
  that reference the credential. The first two names show in the row. Click **+N
  more** to see the rest. A credential nothing uses shows **Not referenced**.
- **Last Rotated** - the date of the last rotation, or a dash if the value was
  never rotated.
- **Created By** - the email address of the person who created the credential.

Use **Search credentials** to find a credential by its name, description,
department, allowed hosts, or the name of anything that uses it. On a narrow
screen, each credential shows as a card instead of a table row.

## Credential types

Every credential is one of two types. The type describes the shape of the stored
value.

- **Secret text** - opaque secrets like API keys, bearer tokens, and passwords.
- **JSON document** - structured secrets like OAuth service-account credentials.
  The value must be a JSON object or array.

## Department credentials

A credential is org-wide or belongs to one top-level department. The **Department**
and **Allowed Hosts** columns on the vault list show each credential's owner and
hosts.

- **Org-wide** - any tool can use the credential. Custom API sources, external MCP
  servers, knowledge indexes, the Datadog and Google Workspace connectors, and
  [article exports to Guru](https://www.tryrisotto.com/docs/dashboard/knowledge/articles#exporting-an-article-to-guru)
  can use org-wide credentials only.
- **Department** - only the tools of that department can use the credential. A
  department credential needs at least one **allowed host**. A sub-department
  cannot own a credential.

Allowed hosts limit where a credential's value can go. Enter the host only, for
example `api.okta.com` or `okta.com`. A host also covers its subdomains: `okta.com`
covers `acme.okta.com`. A scheme, port, path, or wildcard is refused with "Enter a
hostname such as api.example.com, with no scheme, port, path or wildcard." When an
[Assistant](https://www.tryrisotto.com/docs/dashboard/assistant) script uses the credential in an HTTP request,
Risotto adds the value only to requests to those hosts and refuses a request to any
other host before it leaves the sandbox. The approval card for the script lists each
credential's hosts. A credential with no allowed hosts can reach any host.

Risotto also checks the allowed hosts in other places that use a credential:

- **Custom API sources**: the host of the source's **Base URL**.
- **External MCP servers**: the host of the server URL, for a bearer token or a header value.
- **Knowledge indexes**: the host of the indexed service, for example `api.notion.com` or your Confluence site.
- **Request HTTP Resource**: the host of each request that uses the credential.
- **Add Jira Users to Project** and the **SimpleMDM** tools: the host of the tool's base URL.
- **Script tools**: the host of each `http.*` call that sends an `env.*` key, in published script runs and in script tests. Risotto reads the hosts at the start of each run, so an edit applies to the next run without republishing. A refused call fails with an error like "http.post() to `api.example.com` refused: `env.API_KEY` reaches `okta.com` and its subdomains only."

If a run would send the credential to a host outside its allowed hosts, Risotto refuses the run. The error names the credential and its allowed hosts, for example "references vault credential `okta-token`, which may be sent only to `okta.com` and subdomains". Fix the destination, or select a different credential.

Each refusal in these places also adds a **Vault Credential Blocked by Allowed Hosts** error on the [Alerts](https://www.tryrisotto.com/docs/dashboard/alerts) page, and posts it to your [notifications channel](https://www.tryrisotto.com/docs/dashboard/settings/notifications) if you have one. A refusal in an Assistant script adds no alert. The alert names the credential, the config field that holds it, the allowed hosts, and the refused host when Risotto knows it. It never includes the value. For a **Request HTTP Resource** refusal, the alert leaves out the host, because a request can build its host from secret values. Click **Edit the credential** in the alert to open the credential's edit dialog. Risotto keeps one open alert for each credential and config field, and opens a new one only after you dismiss it.

Where a tool picks a credential, the list shows only the credentials that the tool
can use: org-wide credentials, plus the credentials of the tool's own department.
If a field still holds another department's credential, for example after you
change the tool's department, the list shows it disabled with the department that
can use it, for example **Okta read token (IT tools only)**. Pick another
credential for that field.

## Create a credential

You can create a credential from the vault page, or inline from any configuration
that accepts a vault reference (see [Reference a credential](#reference-a-credential)).

1. **Open the create dialog**

   On the **Credentials** tab, click **Create Vault Credential**. On a phone, the
   button is labeled **Create**.

   *Product example: The Credentials tab of Settings, Credential Vault, listing each credential's type, department, allowed hosts and users, with Create Vault Credential highlighted.*

2. **Enter a name**

   Enter a descriptive **Name**, for example `Datadog API key`. This is how you
   pick the credential from a list later. Names are unique in your organization,
   ignoring case.

3. **Choose the type**

   Pick the **Type**: **Secret text** or **JSON document**.

4. **Enter the value**

   Paste the **Value**. For secret text, the field is masked. For a JSON
   document, paste the JSON, or click **Choose File** to load it from a `.json`
   file, such as a downloaded service-account key.

5. **Add a description**

   Optionally, add a **Description** of up to 500 characters that says what the
   credential is for. It shows under the name in the list.

6. **Choose the department**

   Next to **Department**, pick **Org-wide** or a top-level department. An Org
   Admin, Manager, or Supervisor can pick **Org-wide** or any top-level
   department. A Supervisor who creates a credential in a department they don't
   supervise can't see or use it afterwards.

7. **Add the allowed hosts**

   Under **Allowed Hosts**, type each host and press Enter. A department
   credential needs at least one host. An Org Admin or Manager can leave an
   org-wide credential without hosts, so it can reach any host. A Supervisor
   must add at least one host in every case.

8. **Create the credential**

   Click **Create Vault Credential**. Risotto shows "Credential created". The
   value is encrypted and stored write-only.

   *Product example: The Create Vault Credential dialog filled in for an IT credential with one allowed host, with Create Vault Credential highlighted.*

If the name is already taken, the dialog shows "A credential with this name
already exists." under **Name**.

> **Warning:** Any admin can reference an org-wide credential from any tool, including tools
> that send it to an external system. When an org-wide credential lists allowed
> hosts, every department Supervisor can use it too. Put a credential in a
> department and list its allowed hosts to limit where it can go, and name
> credentials clearly so their intended use is obvious.

## Reference a credential

Wherever a configuration needs a secret, the field is a vault picker instead of a
text box. The configuration stores a pointer to the credential, not the secret.
The value stays in the vault and is only read at execution time.

1. **Open the picker**

   In the configuration's secret field, click **Choose a vault credential**. The
   list shows only the credentials whose type matches the field and that this
   configuration can use. If none match yet, the list says so.

2. **Pick the credential**

   Click the credential to use.

   *Product example: A custom API source's Bearer token field with the vault picker open on the org-wide credentials and Add a vault credential.*

   To create one instead, choose **Add a vault credential** at the end of the
   list. The create dialog opens with the name filled in from the field, which
   you can change, and the type fixed to match the field. Its department
   choices are **Org-wide** and the tool's own department. When you create the
   credential, the field references it.

3. **Save the configuration**

   Save the tool, source, server, index, or connection as you usually do.

Credentials can be referenced from:

- **Tools** - Basic auth username and password, and Bearer token fields, and the
  HTTP tool's secret key-value fields.
- **[Script tools](https://www.tryrisotto.com/docs/integrations/tools/script-tools#secrets-env)** - every `env.*`
  key the code reads appears as a slot on the tool's **Tool Configuration** card.
- **[Custom API sources](https://www.tryrisotto.com/docs/integrations/tools/custom-api-tools)** - Bearer token,
  API key header value, and Basic auth username and password.
- **[External MCP servers](https://www.tryrisotto.com/docs/integrations/tools/external-mcp-servers)** - static
  Bearer token, and custom header values.
- **Knowledge indexes** - source API tokens and keys (Confluence, Guru, Freshservice,
  Coda, Google Drive service account, Jira, Notion, GitHub, Zendesk, SharePoint).
- **Datadog connection** - Datadog API key and application key.
- **Google Workspace connection** - OAuth client ID and client secret.
- **[Article exports to Guru](https://www.tryrisotto.com/docs/dashboard/knowledge/articles#exporting-an-article-to-guru)** -
  the Guru user API token.

> **Note:** A configuration that still holds a pre-vault raw value shows an **Existing
> value** row. Click **Replace with vault credential** to point it at the vault,
> or the back arrow to keep the existing value. For secret text, the pencil
> button (**Edit raw value**) lets you type a new raw value instead. Leaving the
> row as it is keeps the existing value working.

## Rotate a value

Rotation replaces a credential's secret. The current value is never shown.

1. **Open the rotate dialog**

   On the **Credentials** tab, click the menu button at the end of the
   credential's row and choose **Rotate Value**.

   *Product example: A credential's row menu open on Rotate Value, Edit and Delete, with Rotate Value highlighted.*

2. **Enter the new value**

   Paste the new value in **New value**. For a JSON document, paste the JSON or
   click **Choose File**.

3. **Rotate the value**

   Click **Rotate Value**. Risotto shows "Credential rotated", and the **Last
   Rotated** column shows today's date.

   *Product example: The Rotate Credential dialog with the new value pasted and masked, with Rotate Value highlighted.*

Rotation overwrites the stored value in place. **Everything referencing the
credential picks up the new value on its next run.**

After a rotation, Risotto checks the new value with each external MCP server that
uses the credential as a static bearer token, by connecting to the server. It
does not check other places that use the credential, so make sure the value is
correct before you save it. If a check fails, the **Credentials** tab shows a
callout above the table, for example "1 credential needs attention after its last
rotation". The callout names the credential, the server, and the reason, such as
"The server rejected the credential (HTTP 401)." The credential's name gets a red
mark, and the credential moves to the top of the list. Rotate again with the
correct value, or fix the server's configuration.

## Edit a credential

Editing changes a credential's metadata only. The value is untouched. Use **Rotate
Value** to change the secret itself.

1. **Open the edit dialog**

   In the credential's row menu, choose **Edit**.

2. **Change the fields**

   Update the **Name**, **Description**, **Department**, or **Allowed Hosts**.
   A Supervisor can change only the name and description. The dialog shows the
   department and allowed hosts as read-only text for them.

3. **Save the changes**

   Click **Save Changes**. Risotto shows "Credential updated".

### Move a credential to another department

- A move to **Org-wide** always succeeds. It only widens who can use the credential.
- A move into a department, or from one department to another, is refused while
  anything outside the target department still uses the credential: an org-wide
  tool, a tool in another department, or a custom API source, external MCP server,
  knowledge index, or connector. The dialog shows "Cannot move to" and the
  department, and lists each blocker with its department or kind, with a link for
  each tool. Repoint or move those consumers first, then move the credential.
  Nothing is saved on a refused move, not even a new name entered in the same
  dialog.
- The same rule applies from the tool side. Moving a tool to another department, or
  to org-wide, is refused while the tool still holds a credential of its old
  department. The reason shows under the tool's **Department** field. Change the
  tool's credential fields in the same save to complete the move.

## Delete a credential

1. **Open the delete dialog**

   In the credential's row menu, choose **Delete**.

2. **Confirm**

   In the **Delete Credential?** dialog, click **Delete Credential**. Risotto
   shows "Credential deleted". This can't be undone.

If the credential is still referenced, deletion is blocked. The dialog changes to
**Can't Delete Credential**, says how many places reference it, and lists each one
with its type and configuration field (for example, `Tool · api_key`). Remove
every reference, then delete the credential.

*Product example: The Can't Delete Credential dialog listing the three tools that still reference the credential.*

The **Used By** column on the vault list names everything that references a
credential, so you can see what depends on it before making changes.

## Other credentials and OAuth connections

Org Admins and Managers see two read-only tabs next to **Credentials**:

- **Other credentials** lists integration secrets still stored in each
  integration's own configuration instead of the vault: the integration's name and
  the configuration field, its **Area**, the **Consumer** type, and **Last
  Modified**. Click **Manage** to open the configuration where the secret lives,
  and move it to the vault from there.
- **OAuth** lists OAuth connections (the tab's heading is **OAuth connections**):
  OAuth tool connectors, OAuth MCP servers, and integrations authorized with OAuth.
  Each row shows its **Area**, when it was **Connected**, and a **Status** of
  **Connected**, **Needs reauth**, or **Not connected**. OAuth connections are
  managed where they were authorized. Click **Manage** to go there. You can't
  rotate or reference them from the vault.

On both tabs, the chips above the table filter the rows by area, such as **Chat**,
**Knowledge**, or **Tools**.

## Who can manage the vault

Org Admins and Managers manage every credential. A department **Supervisor** can
open the vault too and manage the credentials of the departments they supervise:

- They see and can use the credentials of the departments they supervise. A
  Supervisor of a sub-department also sees the parent department's credentials.
  They also see the org-wide credentials that list allowed hosts.
- They can rotate the value of a credential that belongs to a department they
  supervise, edit its name and description, and delete it. Parent-department and
  org-wide credentials show in their list without a row menu.
- They can create a credential in any top-level department or org-wide, with at
  least one allowed host. If they create it in a department they do not supervise,
  they cannot use or see it after they create it.
- They cannot change a credential's department or allowed hosts. Those stay with
  Org Admins and Managers, because the allowed hosts limit where the value can go.
- They do not see the **Other credentials** and **OAuth** tabs.

See [Permissions](https://www.tryrisotto.com/docs/operating/permissions) for the full role model.

## How secrets are protected

- **Sent only to allowed hosts.** A credential that has allowed hosts goes only to
  those hosts and their subdomains.
- **Encrypted at rest.** Each value is stored in a private, encrypted record using KMS
  envelope encryption with org-scoped keys. The plaintext is never stored or logged
  alongside the credential.
- **Write-only.** There is no operation anywhere that returns a decrypted value to the
  dashboard. Values are consumed on create and rotate only.
- **Read only at execution time.** A referenced secret leaves the vault only when a
  tool, script, custom API request, or MCP connection actually runs.
- **Scoped to your organization.** A reference can never resolve to a credential in a
  different organization.
- **Audited.** Every create, rotate, edit, delete, and reference change is recorded
  as an organization event.

Source: https://www.tryrisotto.com/docs/dashboard/settings/credential-vault
