---
title: "POST /vault/credential-requests"
method: POST
path: "/vault/credential-requests"
---

# POST /vault/credential-requests

`POST /vault/credential-requests`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/vault/credential-requests`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Request body

- object: Input for creating a human-in-the-loop credential request — the secret is never passed as a tool argument; a human supplies it out-of-band.
  - `agentId` union: Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key.
    - string
    - string
  - `type` 'login' | 'secure_note' | 'card' | 'identity' | 'oauth_token' | 'api_key' | 'certificate', required: Type of credential the human is asked to provide
  - `name` string, required: Display name for the credential to be created
  - `reason` string, required: Human-readable explanation of why the credential is needed, shown to the owner
  - `ttlSeconds` integer: Request TTL in seconds (60-3600, default 900 = 15 minutes)
  - `notifyOwner` boolean: The MCP layer sets this true ONLY on the no-elicitation fallback path; the api emails the fillUrl to the org owner iff true.

## Response `200`

OK

- object: Created credential request — carries the fill URL and pending status, or a synchronously resolved reference
  - `requestId` string, required: Unique credential request identifier
  - `fillUrl` string, required: Token-gated URL where the human submits the secret (fallback / URL-mode path)
  - `status` 'PENDING' | 'FULFILLED' | 'EXPIRED' | 'DECLINED' | 'CANCELLED', required: Current request status
  - `expiresAt` string, date-time, required: When the request expires and the fill URL stops working
  - `emailSent` boolean, required: Whether the fill URL was emailed to the agent owner (false if no humanEmail is set)
  - `credentialId` string, nullable: Resolved vault credential ID when the inline path fulfills synchronously; null otherwise

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)