> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Credential Requests

> Agents ask a human for a secret they must never see — the human fills it out-of-band, the agent gets a reference.

# Credential Requests

When an agent needs a credential it doesn't have — a 401 on a service, a missing API key — it should never ask the human to paste the secret into chat. Instead it creates a **credential request**: the human receives a token-gated fill URL, enters the secret on Anima's page, and the secret goes straight into the vault. The agent polls the request and receives only a **reference** (plus a masked preview like `****1234` to confirm which secret arrived), then uses it via the [broker](/vault-server-side-use) or autofill.

```text theme={null}
Agent: request("Stripe key", reason) ──> fillUrl ──> human opens page, pastes secret
Agent: poll status … PENDING … FULFILLED { credentialId, maskedPreview }
Agent: vault use credentialId  (never sees the value)
```

## Create a request

<CodeGroup>
  ```bash CLI theme={null}
  anima vault request create --type api_key \
    --name "Stripe production key" \
    --reason "Deploy needs to verify billing" \
    --ttl 900 --wait
  ```

  ```ts TypeScript theme={null}
  const req = await anima.vault.credentialRequestCreate({
    type: "api_key",
    name: "Stripe production key",
    reason: "Deploy needs to verify billing",
    ttlSeconds: 900,
  });
  // share req.fillUrl with the human, then poll
  ```

  ```python Python theme={null}
  req = anima.vault.credential_request_create(
      type="api_key",
      name="Stripe production key",
      reason="Deploy needs to verify billing",
      ttl_seconds=900,
  )
  ```

  ```json MCP theme={null}
  // tool: vault_credential_request_create — MCP clients with elicitation
  // support surface the fill UI inline; otherwise the fill URL is returned
  // (and optionally emailed to the org owner with notifyOwner).
  { "type": "api_key", "name": "Stripe production key", "reason": "Deploy needs to verify billing" }
  ```
</CodeGroup>

Requests expire (60–3600 s TTL, default 15 minutes). `--wait` on the CLI polls until the request leaves `PENDING`.

## Track and manage

* **Status** — `credentialRequestStatus(requestId)` returns `PENDING | FULFILLED | EXPIRED | DECLINED | CANCELLED`, the `credentialId` once fulfilled, and the masked preview. Never the secret.
* **List** — `credentialRequestList` enumerates the org's requests (agents see only their own). In the console, **Vault → Requests** shows every ask with its reason, lets you copy a pending fill URL to forward to the right person, and cancel stale requests.
* **Cancel** — `credentialRequestCancel(requestId)` invalidates the fill URL immediately.

Secrets submitted through a fill URL default to the `brokered` [reveal policy](/vault-reveal-policy): the human who typed the secret is the last person who ever sees it.