（待译）

Vault stores write-only credentials through /vault/v1, with a compatibility face at /anthropic/v1/vaults. Concepts and behavior follow Anthropic vaults (credential collections, write-only values, rotation and archival), so Anthropic experience applies. Differences: native secrets use names and static/oauth kinds; native OAuth uses authorizations, while compatible mcp_oauth creation and updates return 501; explicit allowed_hosts are required, with no unrestricted mode; Agent sessions reject nonempty vault_ids, so vault-backed MCP authentication is unavailable; application vault references return 501, including praxis_vault_ref bindings and secret writes with a vault source. Metadata labels do not attach credentials to either resource. Start with praxis.vault.vaults.create to create the containing vault.

用 API Key 作为 Bearer 凭据，通过以下地址管理库与 Secret。Secret 的值只写，任何接口都不会返回。

https://api.deepraxis.ai/vault/v1

指南 →

Secret 可以用名字或 vsec_ 开头的 ID 寻址。列表用 cursor 与 limit 翻页（limit 默认 50，最大 200），返回的 next_cursor 为 null 表示没有后续页。

同一批库也可以通过 Claude 托管智能体的凭据库接口访问：Claude 托管智能体

错误码

创建和管理库，检查可用状态，并查询不含 Secret 值的审计事件。

指南 →

基础地址与鉴权

审计事件按时间倒序列出，可用 secret 按名称或 ID 过滤；未知 Secret 返回空列表。limit 默认 50、最大 200；超限或无效 cursor 返回 400 INVALID_PARAMS。事件没有按天自动过期的保留期；归档保留事件，删除库或 Secret 会清除其历史事件，仅保留删除记录。

列出库

GET /vault/v1/vaults

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl "https://api.deepraxis.ai/vault/v1/vaults" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

创建库

POST /vault/v1/vaults

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Agent credentials"}'

检查库

POST /vault/v1/vaults:check

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults:check" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"vault_ids\":[\"${VAULT_ID}\"]}"

读取库

GET /vault/v1/vaults/{vault_id}

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

更新库

POST /vault/v1/vaults/{vault_id}

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"team":"growth"}}'

删除库

DELETE /vault/v1/vaults/{vault_id}

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X DELETE "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

归档库

POST /vault/v1/vaults/{vault_id}/archive

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

查看事件

GET /vault/v1/vaults/{vault_id}/events

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/events" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

Vault

VaultPage

VaultEvent

添加、导入和更新 Secret；值只写，校验与续期仅用于 OAuth Secret。

指南 →

基础地址与鉴权

导入同名 Secret 只替换值；只有该行自己的 allowed_hosts 才能改变原域名，顶层默认域名不覆盖已有域名。新建行优先使用该行域名，否则使用顶层默认域名。逐行失败在 HTTP 200 的 failed 中返回（包括 SECRET_TOO_LARGE、VAULT_LIMIT_EXCEEDED、INVALID_PARAMS），其它行仍然写入。用非法名称查找 Secret 返回 404 SECRET_NOT_FOUND。

列出 Secret

GET /vault/v1/vaults/{vault_id}/secrets

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

添加 Secret

POST /vault/v1/vaults/{vault_id}/secrets

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"GITHUB_TOKEN","value":"ghp_example","allowed_hosts":["api.github.com"]}'

批量导入

POST /vault/v1/vaults/{vault_id}/secrets:import

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets:import" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dotenv":"OPENAI_API_KEY=sk-example\nLINEAR_API_KEY=lin_example","allowed_hosts":["api.openai.com","api.linear.app"]}'

读取 Secret

GET /vault/v1/vaults/{vault_id}/secrets/{secret}

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

更新 Secret

POST /vault/v1/vaults/{vault_id}/secrets/{secret}

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"ghp_rotated"}'

删除 Secret

DELETE /vault/v1/vaults/{vault_id}/secrets/{secret}

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X DELETE "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

归档 Secret

POST /vault/v1/vaults/{vault_id}/secrets/{secret}/archive

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/GITHUB_TOKEN/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

校验 Secret

POST /vault/v1/vaults/{vault_id}/secrets/{secret}/validate

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

仅适用于 OAuth Secret。先完成一键授权，并将返回的 secret_id 设为 OAUTH_SECRET_ID；不要使用 static Secret。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/${OAUTH_SECRET_ID}/validate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

续期 Secret

POST /vault/v1/vaults/{vault_id}/secrets/{secret}/refresh

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

仅适用于 OAuth Secret。先完成一键授权，并将返回的 secret_id 设为 OAUTH_SECRET_ID；不要使用 static Secret。

curl -X POST "https://api.deepraxis.ai/vault/v1/vaults/${VAULT_ID}/secrets/${OAUTH_SECRET_ID}/refresh" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"unauthorized"}'

Secret

SecretOAuthSummary

ImportLine

ImportResult

SecretValidation

HttpCapture

查询常用服务的模板 ID、Secret 名称、种类和允许域名。

指南 →

基础地址与鉴权

列出模板

GET /vault/v1/templates

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。 没有额外的领域错误。

curl "https://api.deepraxis.ai/vault/v1/templates" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

VaultTemplate

让用户授权第三方服务，并管理一次性授权链接与回跳地址。

指南 →

基础地址与鉴权

一键授权为支持 OAuth 的服务产生 kind 为 oauth 的 Secret。发起授权后把 connect_url 交给最终用户；用户在确认页同意并在服务方完成授权后，Secret 写入库中，之后由平台续期。确认页、回调与客户端元数据三个地址不需要 API Key。

发起授权

POST /vault/v1/authorizations

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X POST "https://api.deepraxis.ai/vault/v1/authorizations" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"vault_id\":\"${VAULT_ID}\",\"template_id\":\"linear\"}"

读取授权

GET /vault/v1/authorizations/{authorization_id}

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl "https://api.deepraxis.ai/vault/v1/authorizations/${AUTHORIZATION_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

读取回跳地址

GET /vault/v1/settings/return_urls

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。 没有额外的领域错误。

curl "https://api.deepraxis.ai/vault/v1/settings/return_urls" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

设置回跳地址

PUT /vault/v1/settings/return_urls

请求体

响应

HTTP 200

application/json

错误响应

缺少或无效的 API Key 返回 401 UNAUTHENTICATED。

curl -X PUT "https://api.deepraxis.ai/vault/v1/settings/return_urls" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://app.example.com/connected"]}'

授权回调

GET /vault/v1/authorizations/callback · 无需 API Key

响应

HTTP 200

text/html

浏览器显示的确认页或结果页。

HTTP 302

通过 Location 响应头跳转到服务方授权页或已允许的回跳地址。

错误响应

设置了 return_url 时返回 302；未设置时返回 HTTP 200 结果页。

curl "https://api.deepraxis.ai/vault/v1/authorizations/callback"

OAuth 客户端元数据

GET /vault/v1/oauth/client.json · 无需 API Key

响应

HTTP 200

application/json

错误响应

没有额外的领域错误。

curl "https://api.deepraxis.ai/vault/v1/oauth/client.json"

授权确认页

GET /vault/v1/connect/{token} · 无需 API Key

响应

HTTP 200

text/html

浏览器显示的确认页或结果页。

HTTP 410

text/html

浏览器显示的确认页或结果页。

错误响应

无效链接返回 404；过期或已使用的链接返回 410，均为 HTML 页面。

curl "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}"

继续授权

POST /vault/v1/connect/{token}/continue · 无需 API Key

响应

HTTP 302

通过 Location 响应头跳转到服务方授权页或已允许的回跳地址。

错误响应

curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/continue"

拒绝授权

POST /vault/v1/connect/{token}/deny · 无需 API Key

响应

HTTP 200

text/html

浏览器显示的确认页或结果页。

HTTP 302

通过 Location 响应头跳转到服务方授权页或已允许的回跳地址。

错误响应

设置了 return_url 时返回 302；未设置时返回 HTTP 200 结果页。

curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/deny"

Authorization

ReturnUrls

错误响应体统一为下面的形状；code 是稳定的错误码，message 给人读。

{
  "request_id": "req_example",
  "error": {
    "code": "SECRET_CONFLICT",
    "message": "A secret named GITHUB_TOKEN already exists",
    "kind": "validation_failure",
    "recovery": "none",
    "retryable": false
  }
}

错误体包含 request_id，可用于定位请求。兼容接口使用下列错误形状；409 的类型为 conflict_error，不可重试的错误带 x-should-retry: false。

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A credential with this name already exists"
  },
  "request_id": "req_example"
}