---
title: "Ask a human for a credential"
method: POST
path: "/v1/secret-requests"
tags: ["Secrets"]
---

# Ask a human for a credential

`POST /v1/secret-requests`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/secret-requests`
- Auth: HTTP bearer

Agent-authenticated. The agent says what it needs and why; the human sees a secure field in the dashboard, stores the value straight into the vault over their own session, and the agent is later told **where** it went — never what it is.

This exists because the alternative is worse than it looks. Typing a credential into runtime chat persists it to the conversation, writes it into the agent's memory, and replays it to the model on every later turn: one paste, four copies, no way back.

One open request per agent per label: asking again with the same label refreshes the existing one rather than queueing a duplicate. Unanswered requests expire after 24 hours.

## Request body

- object
  - `label` string, required
  - `purpose` string, required: Shown to the person being asked. They are handing over a secret and need to know what for.
  - `suggested_path` string, nullable: A suggestion only — the human picks the vault and may change the path.

## Response `202`

Asked. Poll the status route; do not ask in conversation.

- object
  - `id` string, uuid, required
  - `status` string, required
  - `expires_at` string, date-time, required
  - `next` string, required

## Other responses

- `400`: Missing label or purpose, or an invalid suggested path
- `403`: Not an agent. A person storing a credential uses the vault directly.

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/5fa0918f3b41?raw)