Agents and approvals
Let an agent use a credential from the codai Vault without seeing its value. Expose an item with a handle and allowed hosts, approve requests on your phone, watch, desktop or in the hub, and set decoy items that raise an alarm.
An agent never gets the value of a vault item. You give an item a handle, the agent writes that handle where the secret should go, and a codai app puts the real value in at the last moment: into the command that runs, or into the HTTPS call. The agent sees the result with the value removed.
Nothing in the vault is visible to agents until you expose it.
Expose an item to agents
You do this in the hub.
- Open the item and find Agent access. Turn the switch on.
- Fill in:
- Handle: lowercase letters, digits,
-and_. Agents write it as{{vault:handle}}. - Name shown to agents: the only description an agent sees.
- Sensitivity: Low, Normal, High or Critical.
- Allowed hosts: the credential can only be sent to these hosts, for example
api.github.com. Anything else is blocked and logged. - Env variable: the name under which the value is given to a command, for example
GITHUB_TOKEN.
- Handle: lowercase letters, digits,
- Choose Expose to agents. The item shows Visible to agents.
To hide it again, turn the switch off. Agents lose access at once.
Agent access is not offered for a Secure note, a Card or an Identity.
Shared vaults
Only an Owner or a Manager of a vault can change agent access, the allowed hosts or the honeytoken mark of its items. An Editor can change the content of an item, not who may use it.
How an agent uses a credential
- In a terminal:
codaid vault run -- <command>replaces every{{vault:handle}}in the command and in the environment, gives the values to that command only, and removes them from its output. The agent sees a marker such as[vault:github]where the value was. - Through MCP: the tools
vault_listandvault_rundo the same for an MCP client. See Clients. - As an HTTPS call made by codai: only for an item that is usable in the cloud.
When an agent needs a secret you do not have yet, it sends you a link instead of asking you to paste the value into the chat. The page is called Add a secret for your agent. You type the value there, it is encrypted in your browser, and the agent receives only the handle. The link is valid for 10 minutes. Check that the address bar shows hub.codai.ro.
Decide how much to ask: tiers
The Policies tab sets how each request is handled.
| Tier | What happens |
|---|---|
| T0 · metadata only | The agent sees that the item exists and cannot use it. |
| T1 · automatic, logged | The use is allowed and recorded. |
| T2 · automatic + notify | The use is allowed and you are notified. |
| T3 · ask me | You approve or deny each request. |
| T4 · ask + passkey/biometric | You approve with a passkey or with a device that checks your fingerprint or face. |
| Never | Every request is denied. |
Default for agents applies to every item without a rule. Critical items (SSH keys, cards, passkeys) need T4 unless a rule says otherwise. Under Rules you set a tier for one item, one agent or one kind of use. The most specific rule wins. The allowed hosts and honeytokens cannot be overridden by a rule.
Anomaly checks on the same tab raise a request to T4 when the host was not used with that item in the last 30 days, when requests come in a burst, or outside the hours you allow.
Approve or deny a request
A request shows the agent, the item, how it will be used, the destination host, the exact command or call and the purpose the agent gave. Read the command, not only the purpose.
- Allow for sets how long your answer holds: Once, This task, 1 hour or 8 hours.
- When three numbers are shown, tap the one the agent displays on its side. A wrong number denies the request.
- Deny works from every device and needs no check.
- A request expires if nobody answers.
| Where | Standard requests (T3) | Sensitive requests (T4) |
|---|---|---|
| Hub, Approvals tab | Approve | Approve with passkey: needs a passkey on your codai account |
| Desktop app | Agent requests, then allow once, for the task or for 1 hour | Windows Hello, after Enrol approval key |
| Android phone | After Enrol this phone, with fingerprint or face | Yes, the same way |
| Wear OS watch | Approve on the watch, for one use | No: the watch says Approve on your phone or computer |
| iPhone | After Enable approvals on this iPhone | No: approve on an Android phone, on desktop or in the hub |
The phone and the watch get a notification for each request. The watch sets up its approval key with the phone nearby, and the phone asks you to allow it.
For a shared vault, Quorum approvals on the Vaults tab can require several owners or managers to approve the same request. One deny ends it.
See and end what you allowed
- Live leases on the Policies tab lists the access you approved for a task or a time window. Revoke ends one, End task ends everything a task holds. The Android app has the same list on the Live access tab, the desktop app under Live grants.
- Usage limits on an exposed item cap how often agents may use it: per minute, per day and in units per day.
- Activity records every change, agent use, denial and approval. Values are never recorded.
- Deny + lock refuses everything at once: every live lease is revoked, every pending request is denied, and agents get nothing until you unlock. Unlock in the hub with Unlock with passkey, or on an enrolled Android phone with Unlock agent access. The desktop app cannot unlock.
Decoy items (honeytokens)
A honeytoken is an item that no real task needs. Its value is fake and its name looks tempting. An agent that asks to use it is doing something you did not ask for.
- Turn on Honeytoken at the bottom of an item in the hub.
- A request to use it is denied, and the vault locks itself for agents. The hub shows Security alarm: a honeytoken was touched, and the phone gets an alarm notification with the agent and the machine. Check Activity before you unlock.
codaid vault importadds two decoy API keys for each imported project. Use--no-honeytokensto skip them.- Honeytokens are left out of an export.
Related
Delete and undo
What happens when you delete an item from the codai Vault. The Undo window on each device, when the delete reaches your other devices, how long codai keeps the encrypted data, and how the duplicate passkey clean-up picks the copy to keep.
Export, password and Secret Key
Export your codai Vault to a file other password managers can read, change the vault password, and replace the Secret Key and the recovery kit. All three are done in the hub.