# Secrets an agent uses but never sees

> Keep an API key in a secret field, approve the one host it may go to, and let your agent call that host without ever reading the key.

Kind: concept · ~3 min · Verified v0.237.0 · Next: [Signatures: agents ask, people sign](https://pr-2197-stg.superartifacts.app/docs/concepts/signing.md)

```mermaid
%% hand-drawn: public/docs/diagrams/secrets.svg is an animated SVG; this is its text twin.
flowchart LR
  P["You: type the key into an entry"] --> V[("Vault, sealed")]
  A["Agent: super_secret_use, value redacted"] -->|asks to use it| V
  V -->|first time: approve one host?| P
  P -->|approve: 24 hours, 50 uses| G["Grant"]
  G -->|key in one header| H["api.example.com only"]
  H -->|scrubbed answer| A
```

A **secret field** is a collection field marked `pii: secret`. Its value is encrypted and write-only: entry reads say only whether it is set. Only the workspace owner can reveal it, from the entry in the dashboard, and each reveal is recorded.

## Adding one

Ask your agent to define a collection with a `pii: secret` field, for example `api_key` in a collection of services. Then open the entry in the dashboard and type the value yourself. Typed there, it never passes through a chat.

## How your agent uses it

The agent calls `super_secret_use` with the collection, the entry, the field and the request it wants made: the method and an `https` address. It never holds the value. The platform opens the vault inside its own process, puts the value into **one header** (such as `authorization: Bearer …`), calls the host, and searches the answer for the key before handing it back. An answer that echoes the key is withheld whole.

## The approval card

The first request for a field and a host stops with `approval_required` and a link. The workspace owner opens it and sees:

- which agent is asking, and for which secret;
- the **host**, drawn large, so a lookalike address stands out;
- the methods, the header, an expiry (**24 hours** by default, at most 30 days) and a use cap (**50** by default, at most 1000).

Approve it, narrow it to a subdomain or fewer methods, or refuse it. A refusal stands for a day. Pending and active grants appear on the Secret use page, where an active grant can be revoked. Grant decisions and uses are recorded in the workspace audit log; reading it follows your plan.

## What your agent never sees

The platform does not return or log the value. It checks for raw and common encoded echoes; a host that hashes, truncates or encrypts the credential before reflecting it can evade that check. It cannot send the key to any host but the approved one, and redirects are never followed.

## Honest limits

- It **limits, logs and lets you revoke** every use. It does not promise that a hijacked agent cannot misuse a granted secret on the host you approved, so approve the narrowest host and the shortest expiry that does the job.
- The key goes into a **header only**, never into the address or the body.
- **Collection entries only.** A secret a visitor submits through a page was given to that page, not to your agent, and cannot be used this way.
- It **cannot configure software on your own computer**. For that, reveal the value yourself in the dashboard and paste it where it goes.

## Call limits

Each agent may create 10 pending grants an hour per workspace. A grant permits at most 120 uses an hour, within its approved total. Request bodies allow 64 KiB. The platform reads up to 256 KiB of response and returns up to 64 KiB, with `bodyTruncated` when cut. Connection and total timeouts are five and fifteen seconds. Compressed responses that cannot be checked are refused.

`no_agent` means the credential has no agent identity; use the connected agent's key. `upstream_timeout` means the call timed out; `upstream_failed` includes refused private destinations and unreadable compressed answers. Failed calls can consume a use once admitted.

Start with [Use stored secrets](https://pr-2197-stg.superartifacts.app/docs/secrets.md). The [REST operations](https://pr-2197-stg.superartifacts.app/docs/reference/api-endpoints.md) list a secret-use route, but its workspace-key requirement conflicts with the agent identity required by the collection route. Use MCP for this workflow.

Next: [Signatures](https://pr-2197-stg.superartifacts.app/docs/concepts/signing.md)
