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

# Set up a Session credential Vault

> Create a Vault through the public HTTP API and select it in a Session draft.

A Vault holds credentials for tools and services used by a Session. Model provider
keys belong in [Model credentials](https://app.checkfu.com/model-credentials),
not in a Vault. A Session that does not need service credentials can proceed
without a Vault.

The Console currently lists Vaults and selects them for new Sessions. Create and
manage them through the public HTTP API. No private CLI or SDK package is needed.
Creating a Vault does not start a Session or a Run and does not establish that a
runtime can use its credentials.

<Warning>
  Plain HTTP against the Checkfu API needs no private package.
  Live readiness is deployment- and Workspace-specific and is not asserted by this page.
  Confirm [capability status](/getting-started/status) before making availability part of your application's contract.
</Warning>

## Before you start

Use a developer or administrator API key with write authority for the same
Workspace selected in the Console. A read-only viewer key cannot create a Vault
or add credentials. API keys are
Workspace-bound; changing a browser tab does not change a key's Workspace. See
[API access](/reference/access) and [request conventions](/reference/overview).
These examples require `curl`, `jq`, and `openssl`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CHECKFU_API_KEY="your_workspace_api_key"
CHECKFU_VAULT_SETUP_ID="$(openssl rand -hex 16)" && export CHECKFU_VAULT_SETUP_ID
```

Keep this setup ID for retries of this same creation request. Use a new ID for a
separate Vault. Stop if a request fails; do not continue with an empty Vault ID.

## 1. Create the Vault

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
unset VAULT_ID
VAULT_RESPONSE="$(curl --fail-with-body --silent --show-error \
  -X POST https://api.checkfu.com/v1/vaults \
  -H "Authorization: Bearer $CHECKFU_API_KEY" \
  -H "Checkfu-Version: 2026-08-31" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vault-setup-$CHECKFU_VAULT_SETUP_ID" \
  -d '{"display_name":"Service credentials"}')" && \
VAULT_ID="$(printf '%s' "$VAULT_RESPONSE" | jq -er '.id | select(type == "string" and test("^vlt_[0-9a-f]{32}$"))')" && \
export VAULT_ID
```

An HTTP error is a failed creation step. If the response is lost, retry the
unchanged request with the same idempotency key instead of creating another
Vault. Save the returned `vlt_…` ID for subsequent operations.

## 2. Add the appropriate credential

Credential creation is a protected human setup operation. It is not exposed
as a model-facing MCP tool. Use the Vault credential creation endpoint in the
[Create a credential API reference](/api-reference/vaults/create-a-credential):
`POST /v1/vaults/{vault_id}/credentials`. Choose an auth variant for the service:

| Auth type | Required inputs | Intended use |
| - | - | - |
| `static_bearer` | `token`, `mcp_server_url` | An MCP service accepting a bearer token. |
| `mcp_oauth` | `access_token`, `mcp_server_url` | An MCP service with an existing OAuth token; the contract also supports expiry and refresh configuration. |
| `environment_variable` | `secret_name`, `secret_value`, `networking` | A named service credential with explicit networking restrictions. |

For limited networking, `allowed_hosts` contains bare hostnames or IPv4 addresses,
not URLs. Consult the generated contract for validation, limits, refresh fields,
and injection locations before submitting a credential.

Submit real secrets from a trusted backend or protected local input. Do not put
them in a Session message, screenshot, repository, or example copied into an
issue. Credential responses omit secret material: a readback confirms metadata
and auth configuration, not the original token or secret value. Keep the source
secret in your own secure custody.

Use a separate stable idempotency key for each credential creation. If that
request has an uncertain outcome, retry its unchanged body with that key rather
than adding a duplicate credential. Do not assume that a stored token proves
provider authorization, renewal, or successful runtime use.

## 3. Confirm the Vault and select it

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail-with-body --silent --show-error \
  "https://api.checkfu.com/v1/vaults/$VAULT_ID" \
  -H "Authorization: Bearer $CHECKFU_API_KEY" \
  -H "Checkfu-Version: 2026-08-31"
```

Open [Vaults](https://app.checkfu.com/vaults) in the same Workspace and refresh
that page if it was open during API creation. Confirm the Vault name. In a new
Session draft, select the Vault in the credential Vault picker. API authors add
its ID to the `vault_ids` array of their Session creation request.

Selecting a Vault in a draft does not create a Session. Check the Agent,
Environment, permission and runtime prerequisites before submitting the Session.
A saved Vault and a selected draft resource are setup evidence; successful
service access requires a qualified runtime and the actual tool or service flow.

## Update and remove credentials

The public API provides [credential read](/api-reference/vaults/get-a-credential),
[update](/api-reference/vaults/update-a-credential),
[archive](/api-reference/vaults/archive-a-credential) and
[delete](/api-reference/vaults/delete-a-credential) operations. Use their generated
schemas and stable mutation keys, then verify the resource state. Rotation, provider revocation and active Session behavior need deliberate
verification; changing a stored credential does not by itself prove those
outcomes. Avoid deleting a Vault while customers still depend on it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.