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.
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.
- 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.
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.
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 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 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.comor 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 anenv.*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() toapi.example.comrefused:env.API_KEYreachesokta.comand 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 page, and posts it to your notifications channel 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).
Open the create dialog
On the Credentials tab, click Create Vault Credential. On a phone, the button is labeled Create.
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.Choose the type
Pick the Type: Secret text or JSON document.
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
.jsonfile, such as a downloaded service-account key.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.
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.
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.
Create the credential
Click Create Vault Credential. Risotto shows "Credential created". The value is encrypted and stored write-only.
If the name is already taken, the dialog shows "A credential with this name already exists." under Name.
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.
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.
Pick the credential
Click the credential to use.
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.
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 - every
env.*key the code reads appears as a slot on the tool's Tool Configuration card. - Custom API sources - Bearer token, API key header value, and Basic auth username and password.
- 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 - the Guru user API token.
Rotate a value
Rotation replaces a credential's secret. The current value is never shown.
Open the rotate dialog
On the Credentials tab, click the menu button at the end of the credential's row and choose Rotate Value.
Enter the new value
Paste the new value in New value. For a JSON document, paste the JSON or click Choose File.
Rotate the value
Click Rotate Value. Risotto shows "Credential rotated", and the Last Rotated column shows today's date.
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.
Open the edit dialog
In the credential's row menu, choose Edit.
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.
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
Open the delete dialog
In the credential's row menu, choose Delete.
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.
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 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.
Something wrong or missing? Report an issue · View as Markdown