# 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.185.0 · Next: [Signatures: agents ask, people sign](https://pr-1797-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. Every grant is listed on the Secret use page, where one click revokes it, and every use is logged in the workspace audit log.

## What your agent never sees

The value: not in what it sends, not in any answer, not in a log. 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.

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