库

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

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

列出库

GET /vault/v1/vaults

参数	位置	说明
cursor	query	上一页返回的 next_cursor。
limit	query	每页条数。 (默认: 50) (1–200)
include_archived	query	是否包含已归档的条目。 (默认: false)

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
data	Vault[]	是	条目数组
data[].id	string	是	对象标识符
data[].type	"vault"	是	对象类型
data[].display_name	string	是	显示名称，1–255 个字符
data[].metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
data[].status	"active" / "archived"	是	状态
data[].secret_count	integer	是	有效 Secret 数
data[].needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
data[].created_at	date-time	是	创建时间
data[].updated_at	date-time	是	更新时间
data[].archived_at	date-time / null	是	归档时间；未归档时为 null
next_cursor	string / null	是	下一页游标；没有后续时为 null

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否

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

创建库

POST /vault/v1/vaults

请求体

字段	类型 / 枚举	必填	说明
display_name	string	是	显示名称，1–255 个字符
metadata	object	否	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault"	是	对象类型
display_name	string	是	显示名称，1–255 个字符
metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
status	"active" / "archived"	是	状态
secret_count	integer	是	有效 Secret 数
needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
archived_at	date-time / null	是	归档时间；未归档时为 null

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否

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

请求体

字段	类型 / 枚举	必填	说明
vault_ids	string[]	是	要检查的库 ID

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
data	object[]	是	条目数组
data[].vault_id	string	是	库 ID
data[].status	"ok" / "not_found" / "archived"	是	状态

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否

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}

参数	位置	说明
vault_id	path	库 ID。

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault"	是	对象类型
display_name	string	是	显示名称，1–255 个字符
metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
status	"active" / "archived"	是	状态
secret_count	integer	是	有效 Secret 数
needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
archived_at	date-time / null	是	归档时间；未归档时为 null

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否

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

更新库

POST /vault/v1/vaults/{vault_id}

参数	位置	说明
vault_id	path	库 ID。

请求体

字段	类型 / 枚举	必填	说明
display_name	string	否	显示名称，1–255 个字符
metadata	object	否	按键合并：字符串写入，null 删除，省略的键保留；自定义标签最多 16 对

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault"	是	对象类型
display_name	string	是	显示名称，1–255 个字符
metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
status	"active" / "archived"	是	状态
secret_count	integer	是	有效 Secret 数
needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
archived_at	date-time / null	是	归档时间；未归档时为 null

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否
VAULT_INVALID_STATE	409	向已归档的库或 Secret 写入；改用有效资源	validation_failure	none	否
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否

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}

参数	位置	说明
vault_id	path	库 ID。

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_deleted"	是	对象类型

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否

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

参数	位置	说明
vault_id	path	库 ID。

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault"	是	对象类型
display_name	string	是	显示名称，1–255 个字符
metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
status	"active" / "archived"	是	状态
secret_count	integer	是	有效 Secret 数
needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
archived_at	date-time / null	是	归档时间；未归档时为 null

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否

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

参数	位置	说明
vault_id	path	库 ID。
secret	query	Secret 名称或 vsec_ 开头的 ID。
cursor	query	上一页返回的 next_cursor。
limit	query	每页条数。 (默认: 50) (1–200)

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
data	VaultEvent[]	是	条目数组
data[].id	uuid	是	对象标识符
data[].type	"vault.created" / "vault.updated" / "vault.archived" / "vault.deleted" / "vault_secret.created" / "vault_secret.updated" / "vault_secret.archived" / "vault_secret.deleted" / "vault_secret.used" / "vault_secret.refreshed" / "vault_secret.refresh_failed" / "vault_authorization.completed" / "vault_authorization.failed" / "vault_authorization.expired"	是	对象类型
data[].secret_id	string / null	是	关联的 Secret ID；未关联时为 null
data[].secret_name	string / null	是	关联的 Secret 名称
data[].at	date-time	是	事件或错误发生时间
data[].detail	object / null	是	事件详情，不含 Secret 值；更新事件的 changed 列出变更字段
data[].detail.changed	string[]	否	本次更新的字段名，例如 value、allowed_hosts
next_cursor	string / null	是	下一页游标；没有后续时为 null

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否

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

Vault

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault"	是	对象类型
display_name	string	是	显示名称，1–255 个字符
metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
status	"active" / "archived"	是	状态
secret_count	integer	是	有效 Secret 数
needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
archived_at	date-time / null	是	归档时间；未归档时为 null

VaultPage

字段	类型 / 枚举	必填	说明
data	Vault[]	是	条目数组
data[].id	string	是	对象标识符
data[].type	"vault"	是	对象类型
data[].display_name	string	是	显示名称，1–255 个字符
data[].metadata	object	是	自定义标签最多 16 对，键最长 64 字符，值最长 512 字符
data[].status	"active" / "archived"	是	状态
data[].secret_count	integer	是	有效 Secret 数
data[].needs_reauthorization_count	integer	是	续期失败、需要重新授权的 OAuth Secret 数
data[].created_at	date-time	是	创建时间
data[].updated_at	date-time	是	更新时间
data[].archived_at	date-time / null	是	归档时间；未归档时为 null
next_cursor	string / null	是	下一页游标；没有后续时为 null

VaultEvent

字段	类型 / 枚举	必填	说明
id	uuid	是	对象标识符
type	"vault.created" / "vault.updated" / "vault.archived" / "vault.deleted" / "vault_secret.created" / "vault_secret.updated" / "vault_secret.archived" / "vault_secret.deleted" / "vault_secret.used" / "vault_secret.refreshed" / "vault_secret.refresh_failed" / "vault_authorization.completed" / "vault_authorization.failed" / "vault_authorization.expired"	是	对象类型
secret_id	string / null	是	关联的 Secret ID；未关联时为 null
secret_name	string / null	是	关联的 Secret 名称
at	date-time	是	事件或错误发生时间
detail	object / null	是	事件详情，不含 Secret 值；更新事件的 changed 列出变更字段
detail.changed	string[]	否	本次更新的字段名，例如 value、allowed_hosts

库

本页内容