Credentials
6 min read
Credentials is the organization's encrypted secret store. Use it for passwords, API keys, accounts, SSH keys, and two-factor codes that agents need to use.
Do not share secrets in a chat
Do not paste keys or passwords into messages to an agent. Store them as credentials to keep them encrypted, assigned, and auditable.
Create a credential
A credential contains the data an agent needs to access one service. For example, you can create one for “Production GitHub” with a username and token, or one for a server with its address, username, SSH key, and two-factor code.
Identify the access
Give it a name that explains the service and its use. Avoid generic names such as “token” or “new account”.
Add only the required fields
Combine the field types that access requires: username, password, URL, API key, SSH key, two-factor code, or note. The note is for non-sensitive instructions; secret values belong in their dedicated fields.
Choose private or team
At the top of the form, Private keeps it for you and the operators you add; Team opens it to every operator, including those who join later. It is private by default.
Assign it to its agents
In the Agents tab, choose which agents can use it. An assigned agent uses it while working without the secret appearing in chat.
Revealing values is controlled by permissions and recorded in the organization's activity.
Who can use it
When an operator talks to an agent, the agent only uses the credential if that operator has access to it: because it is a team credential, because they are on its list, or because they are an owner or admin of the organization and the credential isn't private to someone else. Otherwise, the credential doesn't exist for that agent in that conversation.
Owners and admins see every private credential: its name, description, destinations, who has it and which agents use it. If they aren't on its list, they don't see its values and can't edit, assign or use it. They can archive it, delete it, or remove it from an agent.
In each credential's Operators tab you give each person one of these levels:
| Level | What it allows |
|---|---|
| No access | Nothing. It cannot be chosen on a team credential: everyone has at least Use. |
| Use | An agent can use it in that person's conversations. They don't see it in the dashboard or reveal its values. |
| Manage | Also view it, reveal its values, edit it and assign it. |
Whoever creates a private credential gets Manage. A scheduled task uses the credentials of whoever created it. When an agent asks another agent about something a person on your team asked for, the second agent only uses the credentials that person has access to, also when the request goes through several agents. Webhooks, tasks with no creator and requests between agents with no single person behind them only use team credentials. Connected accounts, such as GitHub or Google, work the same way.
Conversations with clients
By default a credential is Internal: an agent can't use it when it talks to a client, someone outside your organization who writes to it through an external channel such as email or WhatsApp. In those conversations the credential isn't available to it.
If an agent needs a key to serve clients, such as your store's orders API, choose External when you create it or, if it already exists, in its Operators tab. An external credential is always a team one: choosing External makes it Team, and making it Private sets it back to Internal. Keep internal the ones that open internal systems: servers, databases or admin accounts.
The change is recorded in the organization's activity.
This also applies when the agent asks another agent about something a client requested: the second agent answers with the same limits.
Destination
A credential's Destination is the list of addresses where it can be used: api.stripe.com, https://panel.acme.com. The agent uses it only there; sent anywhere else, Kujira does not hand it over. That way an instruction slipped into a page or an email cannot take the key somewhere else. A domain with no subdomain, such as acme.com or *.acme.com, covers the whole domain. An address with a subdomain counts only for itself and its www.: shop.acme.com works on www.shop.acme.com, but not on crm.acme.com. On domains shared by many users, such as github.com, google.com or github.io, only the exact address counts.
If a credential has no destination, or the agent needs it somewhere that is not one of its destinations, it asks you with a card that shows the address:
| Option | What it does |
|---|---|
| Always | Saves that address as a destination of the credential. It does not ask again. |
| Just this once | Lets it be used there for one hour, in that conversation. The credential does not change. |
| No | It is not used. The agent does not ask again in that conversation. |
Whoever is talking to the agent decides, if they have access to the credential. Always does not appear if the address does not match what is already known about the credential —its other destinations or its URL field—, if it is an IP address, or if it is a service that collects whatever is sent to it. To save it anyway, add it yourself in the credential's Destination field.
SSH keys and VPNs do not need a destination: an SSH key only signs, and a VPN only reaches its own network.
SSH keys and two-factor authentication
For an SSH key, the dashboard can generate an Ed25519 pair: the private key is stored encrypted and the public key can be copied to the destination system.
Two-factor fields generate the temporary code when needed. The agent can use it without publishing the underlying secret in a conversation.
Use in scheduled tasks
Script tasks can receive credentials as environment variables while they run. They are not written to the agent's disk. Each field uses its uppercase label; a two-factor field provides the current temporary code.
See Scheduled tasks to configure this automation.
Maintenance
Archived credentials can be recovered when you need them. Review credentials with no assigned agents to remove access that is no longer needed.
Permissions
Credential access is divided so viewing a record does not necessarily reveal its secret. In addition to these permissions, viewing or revealing a credential requires the Manage level on it.
| Action | Permission |
|---|---|
| View the record and its assignments | credential.view |
| Create or modify a credential | credential.edit |
| Archive or delete a credential | credential.delete |
| Reveal a secret value | credential.reveal |
| Manage who can use or manage the credential | credential.grant |