# Use stored secrets

> Approve a bounded API call without putting a credential into your agent’s conversation.

Kind: guide · ~3 min · Verified v0.237.0 · Next: [Access and sharing](https://pr-2197-stg.superartifacts.app/docs/access-and-sharing.md)

## Goal

Let an agent call a service using a credential it cannot read.

## What you'll have

An encrypted secret field and an owner-approved grant: permission for one agent to use that field on one host, within a time and use limit.

## Needs

A content collection entry with a text field classified `pii: secret`, a connected agent with secret-use permission, and the workspace owner to enter the value and approve its use. Visitor submissions cannot be used this way.

## Prompt

**Prepare a secret-backed call.** Your agent prepares the collection and request; you enter the credential and approve the host yourself.

```prompt
Help me call a service using a secret stored in Super Artifacts. Read https://superartifacts.app/docs/secrets.md first. Ask for the service, exact public HTTPS host, method and header format, never the credential. Reuse or define a collection entry with a pii: secret text field. Tell me where to type its value in the dashboard. Call super_secret_use and give me its approvalUrl if approval is required. Wait for approval, then repeat only the agreed request. Never reveal or print the credential, and never bypass an echo refusal.
```

```mermaid
flowchart TB
  O["Owner enters key"] --> V["Encrypted field"]
  A["Agent asks to call"] --> G["Owner approves"]
  G --> I["Inject one header"]
  V --> I
  I --> H["Approved host"]
  H --> S["Check for echoes"]
  S --> R["Scrubbed result"]
```

## Steps

1. Ask your agent to define the collection with `super_data_schema`. Open its entry under **Data → Collections** and type the credential yourself. Entry reads show whether it is set, without returning its value.
2. Ask the agent to call `super_secret_use`, naming the collection, entry, field, method and public HTTPS URL. It proposes one header, such as `authorization` with prefix `Bearer `.
3. The first call returns `approval_required` and an approval link. Open it as the workspace owner. Check the agent, field, exact host, method and header. Approve only the access needed: defaults are 24 hours and 50 uses; maximums are 30 days and 1,000 uses.
4. Have the agent repeat the call after approval. The platform decrypts the value, adds it to the approved header and calls that host. Redirects are not followed.

## Check it worked

The agent gets status, headers and a scrubbed response, never the credential. Open **Secret use** to inspect or revoke the grant. Grant decisions and uses are recorded in the workspace audit log; access to that log follows your plan.

## If not

`secret_echoed` means the service reflected the secret and the whole response was withheld. Do not ask the agent to bypass this. `host_not_allowed` or `method_not_allowed` means the call exceeds the grant. After expiry or exhaustion, a new approval is needed. A denial or revocation stands for a day.

## Variations

Only the workspace owner can reveal a stored value in the dashboard. For software that needs a local credential, enter it yourself there. Secret use sends credentials in a header, never in the URL or body.

## Next

Read [security boundaries and limits](https://pr-2197-stg.superartifacts.app/docs/concepts/secrets.md), [MCP tools](https://pr-2197-stg.superartifacts.app/docs/reference/mcp.md) and [plans](https://pr-2197-stg.superartifacts.app/docs/reference/plans.md).
