Secret

添加、导入和更新 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

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

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
data	Secret[]	是	条目数组
data[].id	string	是	对象标识符
data[].type	"vault_secret"	是	对象类型
data[].vault_id	string	是	库 ID
data[].name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
data[].kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
data[].allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
data[].description	string / null	是	备注；更新时 null 清除，省略则保留
data[].metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
data[].status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
data[].oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
data[].oauth.expires_at	date-time / null	是	过期时间
data[].oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
data[].oauth.next_refresh_at	date-time / null	是	下次计划续期时间
data[].oauth.scope	string / null	是	授权范围
data[].oauth.last_error	object / null	是	最近一次续期失败
data[].oauth.last_error.code	string	是	稳定的错误码
data[].oauth.last_error.message	string	是	可读的错误说明
data[].oauth.last_error.at	date-time	是	事件或错误发生时间
data[].version	integer	是	值每次变化时递增
data[].last_used_at	date-time / null	是	最近一次被使用的时间
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	可重试
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}/secrets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

添加 Secret

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

参数	位置	说明
vault_id	path	库 ID。

请求体

字段	类型 / 枚举	必填	说明
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
value	string	是	Secret 的值，只写，不会返回；最大 16 KiB
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	否	备注；更新时 null 清除，省略则保留
metadata	object	否	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
template_id	"github" / "openai" / "anthropic" / "stripe"	否	仅支持 static 模板 ID；记录为 metadata.template
kind	"static"	否	只能为 static；OAuth Secret 通过一键授权创建

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_secret"	是	对象类型
vault_id	string	是	库 ID
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	是	备注；更新时 null 清除，省略则保留
metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
oauth.expires_at	date-time / null	是	过期时间
oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
oauth.next_refresh_at	date-time / null	是	下次计划续期时间
oauth.scope	string / null	是	授权范围
oauth.last_error	object / null	是	最近一次续期失败
oauth.last_error.code	string	是	稳定的错误码
oauth.last_error.message	string	是	可读的错误说明
oauth.last_error.at	date-time	是	事件或错误发生时间
version	integer	是	值每次变化时递增
last_used_at	date-time / null	是	最近一次被使用的时间
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	否
SECRET_CONFLICT	409	创建时名称已占用；更换名称或更新已有 Secret	validation_failure	none	否
VAULT_LIMIT_EXCEEDED	400	超过有效 Secret 数量上限；先清理不用的 Secret	validation_failure	none	否
SECRET_TOO_LARGE	413	值超过 16384 字节；缩小值后重试	validation_failure	none	否

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

参数	位置	说明
vault_id	path	库 ID。

请求体

字段	类型 / 枚举	必填	说明
lines	ImportLine[]	否	逐行导入的 Secret
lines[].name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
lines[].value	string	是	Secret 的值，只写，不会返回；最大 16 KiB
lines[].allowed_hosts	string[]	否	新建时用本行域名或导入的默认域名；替换时仅本行显式 allowed_hosts 才会更新域名
dotenv	string	否	.env 格式的 KEY=VALUE 文本；与 lines 二选一
allowed_hosts	string[]	否	新建时用本行域名或导入的默认域名；替换时仅本行显式 allowed_hosts 才会更新域名

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
created	string[]	是	新建的 Secret 名称
replaced	string[]	是	被替换的 Secret 名称
failed	object[]	是	失败的行
failed[].line	integer	是	失败行号，从 1 开始
failed[].name	string / null	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
failed[].code	"VAULT_NOT_FOUND" / "SECRET_NOT_FOUND" / "AUTHORIZATION_NOT_FOUND" / "SECRET_CONFLICT" / "VAULT_INVALID_STATE" / "VAULT_LIMIT_EXCEEDED" / "INVALID_PARAMS" / "SECRET_KIND_MISMATCH" / "VALIDATE_UNSUPPORTED" / "SECRET_TOO_LARGE" / "RATE_LIMITED" / "AUTHORIZATION_EXPIRED" / "OAUTH_DISCOVERY_FAILED" / "OAUTH_REGISTRATION_UNSUPPORTED" / "OAUTH_ISSUER_MISMATCH" / "OAUTH_STATE_INVALID" / "OAUTH_EXCHANGE_FAILED" / "NOT_IMPLEMENTED"	是	稳定的错误码
failed[].message	string	是	可读的错误说明

错误响应

缺少或无效的 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}/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}

参数	位置	说明
vault_id	path	库 ID。
secret	path	Secret 名称或 vsec_ 开头的 ID。

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_secret"	是	对象类型
vault_id	string	是	库 ID
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	是	备注；更新时 null 清除，省略则保留
metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
oauth.expires_at	date-time / null	是	过期时间
oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
oauth.next_refresh_at	date-time / null	是	下次计划续期时间
oauth.scope	string / null	是	授权范围
oauth.last_error	object / null	是	最近一次续期失败
oauth.last_error.code	string	是	稳定的错误码
oauth.last_error.message	string	是	可读的错误说明
oauth.last_error.at	date-time	是	事件或错误发生时间
version	integer	是	值每次变化时递增
last_used_at	date-time / null	是	最近一次被使用的时间
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	否
SECRET_NOT_FOUND	404	Secret 不存在，包括用非法名称查找；检查名称或 ID	validation_failure	none	否

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}

参数	位置	说明
vault_id	path	库 ID。
secret	path	Secret 名称或 vsec_ 开头的 ID。

请求体

字段	类型 / 枚举	必填	说明
value	string	否	Secret 的值，只写，不会返回；最大 16 KiB
allowed_hosts	string[]	否	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	否	备注；更新时 null 清除，省略则保留
metadata	object	否	按键合并：字符串写入，null 删除，省略的键保留；source、template 为保留键

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_secret"	是	对象类型
vault_id	string	是	库 ID
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	是	备注；更新时 null 清除，省略则保留
metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
oauth.expires_at	date-time / null	是	过期时间
oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
oauth.next_refresh_at	date-time / null	是	下次计划续期时间
oauth.scope	string / null	是	授权范围
oauth.last_error	object / null	是	最近一次续期失败
oauth.last_error.code	string	是	稳定的错误码
oauth.last_error.message	string	是	可读的错误说明
oauth.last_error.at	date-time	是	事件或错误发生时间
version	integer	是	值每次变化时递增
last_used_at	date-time / null	是	最近一次被使用的时间
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	否
SECRET_NOT_FOUND	404	Secret 不存在，包括用非法名称查找；检查名称或 ID	validation_failure	none	否
VAULT_INVALID_STATE	409	向已归档的库或 Secret 写入；改用有效资源	validation_failure	none	否
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否
SECRET_TOO_LARGE	413	值超过 16384 字节；缩小值后重试	validation_failure	none	否

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}

参数	位置	说明
vault_id	path	库 ID。
secret	path	Secret 名称或 vsec_ 开头的 ID。

响应

HTTP 200

application/json

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

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否
SECRET_NOT_FOUND	404	Secret 不存在，包括用非法名称查找；检查名称或 ID	validation_failure	none	否

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

参数	位置	说明
vault_id	path	库 ID。
secret	path	Secret 名称或 vsec_ 开头的 ID。

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_secret"	是	对象类型
vault_id	string	是	库 ID
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	是	备注；更新时 null 清除，省略则保留
metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
oauth.expires_at	date-time / null	是	过期时间
oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
oauth.next_refresh_at	date-time / null	是	下次计划续期时间
oauth.scope	string / null	是	授权范围
oauth.last_error	object / null	是	最近一次续期失败
oauth.last_error.code	string	是	稳定的错误码
oauth.last_error.message	string	是	可读的错误说明
oauth.last_error.at	date-time	是	事件或错误发生时间
version	integer	是	值每次变化时递增
last_used_at	date-time / null	是	最近一次被使用的时间
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	否
SECRET_NOT_FOUND	404	Secret 不存在，包括用非法名称查找；检查名称或 ID	validation_failure	none	否

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

参数	位置	说明
vault_id	path	库 ID。
secret	path	Secret 名称或 vsec_ 开头的 ID。

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
type	"vault_secret_validation"	是	对象类型
secret_id	string	是	关联的 Secret ID；未关联时为 null
vault_id	string	是	库 ID
validated_at	date-time	是	校验时间
has_refresh_token	boolean	是	是否保存了刷新令牌
status	"valid" / "invalid" / "unknown"	是	状态
probe	object	是	探测请求
probe.method	"GET"	是	探测方式，当前为 GET
probe.http_response	HttpCapture / null	是	HTTP 响应摘要；未收到响应时为 null
probe.http_response.status_code	integer	是	HTTP 状态码
probe.http_response.content_type	string / null	是	响应内容类型，或 null
probe.http_response.body	string	是	已脱敏的响应正文
probe.http_response.body_truncated	boolean	是	正文是否被截断
refresh	object	是	续期结果
refresh.status	"succeeded" / "failed" / "connect_error" / "no_refresh_token" / "skipped"	是	状态
refresh.http_response	HttpCapture / null	是	HTTP 响应摘要；未收到响应时为 null
refresh.http_response.status_code	integer	是	HTTP 状态码
refresh.http_response.content_type	string / null	是	响应内容类型，或 null
refresh.http_response.body	string	是	已脱敏的响应正文
refresh.http_response.body_truncated	boolean	是	正文是否被截断

错误响应

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

错误码	HTTP	含义、触发条件与处理	kind	recovery	可重试
VAULT_NOT_FOUND	404	库不存在或不属于当前账户；检查库 ID	validation_failure	none	否
SECRET_NOT_FOUND	404	Secret 不存在，包括用非法名称查找；检查名称或 ID	validation_failure	none	否
VALIDATE_UNSUPPORTED	400	对 static Secret 校验；校验仅支持 OAuth Secret	validation_failure	none	否
RATE_LIMITED	429	一分钟内超过授权或校验额度；等待下一窗口	rate_limit	wait_then_retry	是

仅适用于 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

参数	位置	说明
vault_id	path	库 ID。
secret	path	Secret 名称或 vsec_ 开头的 ID。

请求体

字段	类型 / 枚举	必填	说明
reason	"unauthorized"	否	触发续期的原因

响应

HTTP 200

application/json

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_secret"	是	对象类型
vault_id	string	是	库 ID
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	是	备注；更新时 null 清除，省略则保留
metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
oauth.expires_at	date-time / null	是	过期时间
oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
oauth.next_refresh_at	date-time / null	是	下次计划续期时间
oauth.scope	string / null	是	授权范围
oauth.last_error	object / null	是	最近一次续期失败
oauth.last_error.code	string	是	稳定的错误码
oauth.last_error.message	string	是	可读的错误说明
oauth.last_error.at	date-time	是	事件或错误发生时间
version	integer	是	值每次变化时递增
last_used_at	date-time / null	是	最近一次被使用的时间
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	否
SECRET_NOT_FOUND	404	Secret 不存在，包括用非法名称查找；检查名称或 ID	validation_failure	none	否
VAULT_INVALID_STATE	409	向已归档的库或 Secret 写入；改用有效资源	validation_failure	none	否
SECRET_KIND_MISMATCH	400	对 static Secret 续期或执行不匹配种类的操作；使用 OAuth Secret	validation_failure	none	否
INVALID_PARAMS	400	字段、名称、域名、metadata、分页或回跳地址无效；修正请求	validation_failure	none	否

仅适用于 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

字段	类型 / 枚举	必填	说明
id	string	是	对象标识符
type	"vault_secret"	是	对象类型
vault_id	string	是	库 ID
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
kind	"static" / "oauth"	是	static：你填写的值；oauth：授权得到、由平台续期
allowed_hosts	string[]	是	1–16 个域名、公网 IPv4 或 .example.com；不匹配根域名。拒绝 IPv6、单标签主机、localhost、.internal、平台域名及回环/链路本地/私网/CGNAT IPv4；规范化并去重
description	string / null	是	备注；更新时 null 清除，省略则保留
metadata	object	是	自定义标签最多 16 对；source、template 为系统保留键，不占这 16 对且不能由调用方写入
status	"active" / "refreshing" / "refresh_failed" / "archived"	是	状态
oauth	SecretOAuthSummary / null	是	OAuth 摘要；kind 为 static 时为 null
oauth.expires_at	date-time / null	是	过期时间
oauth.last_refreshed_at	date-time / null	是	最近一次续期时间
oauth.next_refresh_at	date-time / null	是	下次计划续期时间
oauth.scope	string / null	是	授权范围
oauth.last_error	object / null	是	最近一次续期失败
oauth.last_error.code	string	是	稳定的错误码
oauth.last_error.message	string	是	可读的错误说明
oauth.last_error.at	date-time	是	事件或错误发生时间
version	integer	是	值每次变化时递增
last_used_at	date-time / null	是	最近一次被使用的时间
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
archived_at	date-time / null	是	归档时间；未归档时为 null

SecretOAuthSummary

字段	类型 / 枚举	必填	说明
expires_at	date-time / null	是	过期时间
last_refreshed_at	date-time / null	是	最近一次续期时间
next_refresh_at	date-time / null	是	下次计划续期时间
scope	string / null	是	授权范围
last_error	object / null	是	最近一次续期失败
last_error.code	string	是	稳定的错误码
last_error.message	string	是	可读的错误说明
last_error.at	date-time	是	事件或错误发生时间

ImportLine

字段	类型 / 枚举	必填	说明
name	string	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
value	string	是	Secret 的值，只写，不会返回；最大 16 KiB
allowed_hosts	string[]	否	新建时用本行域名或导入的默认域名；替换时仅本行显式 allowed_hosts 才会更新域名

ImportResult

字段	类型 / 枚举	必填	说明
created	string[]	是	新建的 Secret 名称
replaced	string[]	是	被替换的 Secret 名称
failed	object[]	是	失败的行
failed[].line	integer	是	失败行号，从 1 开始
failed[].name	string / null	是	名称，库内唯一且不可改；1–128 个大写字母、数字或下划线，以字母或下划线开头
failed[].code	"VAULT_NOT_FOUND" / "SECRET_NOT_FOUND" / "AUTHORIZATION_NOT_FOUND" / "SECRET_CONFLICT" / "VAULT_INVALID_STATE" / "VAULT_LIMIT_EXCEEDED" / "INVALID_PARAMS" / "SECRET_KIND_MISMATCH" / "VALIDATE_UNSUPPORTED" / "SECRET_TOO_LARGE" / "RATE_LIMITED" / "AUTHORIZATION_EXPIRED" / "OAUTH_DISCOVERY_FAILED" / "OAUTH_REGISTRATION_UNSUPPORTED" / "OAUTH_ISSUER_MISMATCH" / "OAUTH_STATE_INVALID" / "OAUTH_EXCHANGE_FAILED" / "NOT_IMPLEMENTED"	是	稳定的错误码
failed[].message	string	是	可读的错误说明

SecretValidation

字段	类型 / 枚举	必填	说明
type	"vault_secret_validation"	是	对象类型
secret_id	string	是	关联的 Secret ID；未关联时为 null
vault_id	string	是	库 ID
validated_at	date-time	是	校验时间
has_refresh_token	boolean	是	是否保存了刷新令牌
status	"valid" / "invalid" / "unknown"	是	状态
probe	object	是	探测请求
probe.method	"GET"	是	探测方式，当前为 GET
probe.http_response	HttpCapture / null	是	HTTP 响应摘要；未收到响应时为 null
probe.http_response.status_code	integer	是	HTTP 状态码
probe.http_response.content_type	string / null	是	响应内容类型，或 null
probe.http_response.body	string	是	已脱敏的响应正文
probe.http_response.body_truncated	boolean	是	正文是否被截断
refresh	object	是	续期结果
refresh.status	"succeeded" / "failed" / "connect_error" / "no_refresh_token" / "skipped"	是	状态
refresh.http_response	HttpCapture / null	是	HTTP 响应摘要；未收到响应时为 null
refresh.http_response.status_code	integer	是	HTTP 状态码
refresh.http_response.content_type	string / null	是	响应内容类型，或 null
refresh.http_response.body	string	是	已脱敏的响应正文
refresh.http_response.body_truncated	boolean	是	正文是否被截断

HttpCapture

字段	类型 / 枚举	必填	说明
status_code	integer	是	HTTP 状态码
content_type	string / null	是	响应内容类型，或 null
body	string	是	已脱敏的响应正文
body_truncated	boolean	是	正文是否被截断

Secret

本页内容