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 or autofill.

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

anima vault request create --type api_key \
  --name "Stripe production key" \
  --reason "Deploy needs to verify billing" \
  --ttl 900 --wait

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

req = anima.vault.credential_request_create(
    type="api_key",
    name="Stripe production key",
    reason="Deploy needs to verify billing",
    ttl_seconds=900,
)

// 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" }

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: the human who typed the secret is the last person who ever sees it.

Reveal Policy SecretRef & anima.json

​Credential Requests

​Create a request

​Track and manage

Credential Requests

Create a request

Track and manage