# Agents and approvals (/docs/vault/agents)

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 [#expose-an-item-to-agents]

You do this in the hub.

1. Open the item and find **Agent access**. Turn the switch on.
2. 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`.
3. 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**.

<Callout type="info" title="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.
</Callout>

## How an agent uses a credential [#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_list` and `vault_run` do the same for an MCP client. See [Clients](../gateway/clients.mdx).
- **As an HTTPS call made by codai:** only for an item that is [usable in the cloud](./index.mdx).

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 [#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 [#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 [#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) [#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 import` adds two decoy API keys for each imported project. Use `--no-honeytokens` to skip them.
- Honeytokens are left out of an [export](./export-password.mdx).

## Related [#related]

<Cards>
  <Card
    title="What codai can see"
    href="./index.mdx"
    description="Handles and allowed hosts are stored unencrypted; values are not."
  />
  <Card
    title="Vault API"
    href="../api/gateway/vault.mdx"
    description="Tiers, proofs and device keys for developers."
  />
</Cards>