保险库
一键授权
让用户授权第三方服务，并管理一次性授权链接与回跳地址。
让用户授权第三方服务，并管理一次性授权链接与回跳地址。
一键授权为支持 OAuth 的服务产生 kind 为 oauth 的 Secret。发起授权后把 connect_url 交给最终用户；用户在确认页同意并在服务方完成授权后，Secret 写入库中，之后由平台续期。确认页、回调与客户端元数据三个地址不需要 API Key。
发起授权
POST /vault/v1/authorizations
请求体
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| vault_id | string | 是 | 库 ID |
| template_id | "linear" / "atlassian" | 否 | 支持授权的模板 ID；与 resource_url 二选一 |
| resource_url | string | 否 | 要授权的资源地址，例如 MCP 服务地址 |
| return_url | string | 否 | 授权结束后回到的地址；须在回跳地址白名单内 |
响应
HTTP 200
application/json
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 对象标识符 |
| type | "vault_authorization" | 是 | 对象类型 |
| vault_id | string | 是 | 库 ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | 是 | 状态 |
| resource | string | 是 | 资源地址 |
| secret_name | string | 是 | 关联的 Secret 名称 |
| connect_url | string | 是 | 交给最终用户打开的确认页，30 分钟内有效、只能使用一次 |
| client_registration | "cimd" / "dcr" / null | 是 | cimd：通过客户端元数据 URL 注册；dcr：动态注册客户端；尚未注册时为 null |
| secret_id | string / null | 是 | 关联的 Secret ID；未关联时为 null |
| error | object / null | 是 | 失败原因 |
| error.code | string | 是 | 稳定的错误码 |
| error.message | string | 是 | 可读的错误说明 |
| expires_at | date-time | 是 | 过期时间 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
错误响应
缺少或无效的 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 | 否 |
| RATE_LIMITED | 429 | 一分钟内超过授权或校验额度；等待下一窗口 | rate_limit | wait_then_retry | 是 |
| OAUTH_DISCOVERY_FAILED | 400 | 无法发现服务方 OAuth 配置；检查资源地址 | validation_failure | continue_from_problem | 否 |
| OAUTH_REGISTRATION_UNSUPPORTED | 400 | 服务方不接受自动客户端注册；手动添加凭据 | validation_failure | continue_from_problem | 否 |
| OAUTH_ISSUER_MISMATCH | 400 | 授权服务器与预期不一致；重新检查服务地址 | provider_upstream | retry_from_user | 否 |
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}
| 参数 | 位置 | 说明 |
|---|---|---|
| authorization_id | path | 授权 ID。 |
响应
HTTP 200
application/json
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 对象标识符 |
| type | "vault_authorization" | 是 | 对象类型 |
| vault_id | string | 是 | 库 ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | 是 | 状态 |
| resource | string | 是 | 资源地址 |
| secret_name | string | 是 | 关联的 Secret 名称 |
| connect_url | string | 是 | 交给最终用户打开的确认页，30 分钟内有效、只能使用一次 |
| client_registration | "cimd" / "dcr" / null | 是 | cimd：通过客户端元数据 URL 注册；dcr：动态注册客户端；尚未注册时为 null |
| secret_id | string / null | 是 | 关联的 Secret ID；未关联时为 null |
| error | object / null | 是 | 失败原因 |
| error.code | string | 是 | 稳定的错误码 |
| error.message | string | 是 | 可读的错误说明 |
| expires_at | date-time | 是 | 过期时间 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
错误响应
缺少或无效的 API Key 返回 401 UNAUTHENTICATED。
| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
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
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |
错误响应
缺少或无效的 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
请求体
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |
响应
HTTP 200
application/json
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |
错误响应
缺少或无效的 API Key 返回 401 UNAUTHENTICATED。
| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
|---|---|---|---|---|---|
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |
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
| 参数 | 位置 | 说明 |
|---|---|---|
| code | query | 服务方返回的授权码。 |
| state | query | 发起授权时产生的一次性状态值。 |
| error | query | 服务方拒绝授权时返回的错误。 |
| iss | query | 服务方声明的授权服务器地址。 |
响应
HTTP 200
text/html
浏览器显示的确认页或结果页。
HTTP 302
通过 Location 响应头跳转到服务方授权页或已允许的回跳地址。
错误响应
| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
|---|---|---|---|---|---|
| OAUTH_STATE_INVALID | 400 | 回调 state 缺失、无效或重放；重新发起授权 | validation_failure | none | 否 |
| OAUTH_ISSUER_MISMATCH | 400 | 授权服务器与预期不一致；重新检查服务地址 | provider_upstream | retry_from_user | 否 |
| OAUTH_EXCHANGE_FAILED | 502 | 服务方拒绝授权码换令牌；重新授权 | provider_upstream | retry_from_user | 否 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |
设置了 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
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| client_id | string | 是 | 客户端元数据 URL |
| client_name | string | 是 | 客户端显示名称 |
| redirect_uris | string[] | 是 | 允许的 OAuth 回调地址 |
| token_endpoint_auth_method | "none" | 是 | 令牌端点认证方式 |
| grant_types | "authorization_code" / "refresh_token"[] | 否 | 支持的授权类型 |
| response_types | "code"[] | 否 | 支持的授权响应类型 |
错误响应
没有额外的领域错误。
curl "https://api.deepraxis.ai/vault/v1/oauth/client.json"授权确认页
GET /vault/v1/connect/{token} · 无需 API Key
| 参数 | 位置 | 说明 |
|---|---|---|
| token | path | connect_url 中的一次性令牌。 |
响应
HTTP 200
text/html
浏览器显示的确认页或结果页。
HTTP 410
text/html
浏览器显示的确认页或结果页。
错误响应
| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |
无效链接返回 404；过期或已使用的链接返回 410，均为 HTML 页面。
curl "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}"继续授权
POST /vault/v1/connect/{token}/continue · 无需 API Key
| 参数 | 位置 | 说明 |
|---|---|---|
| token | path | connect_url 中的一次性令牌。 |
响应
HTTP 302
通过 Location 响应头跳转到服务方授权页或已允许的回跳地址。
错误响应
| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |
| OAUTH_DISCOVERY_FAILED | 400 | 无法发现服务方 OAuth 配置；检查资源地址 | validation_failure | continue_from_problem | 否 |
curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/continue"拒绝授权
POST /vault/v1/connect/{token}/deny · 无需 API Key
| 参数 | 位置 | 说明 |
|---|---|---|
| token | path | connect_url 中的一次性令牌。 |
响应
HTTP 200
text/html
浏览器显示的确认页或结果页。
HTTP 302
通过 Location 响应头跳转到服务方授权页或已允许的回跳地址。
错误响应
| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
|---|---|---|---|---|---|
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |
设置了 return_url 时返回 302；未设置时返回 HTTP 200 结果页。
curl -X POST "https://api.deepraxis.ai/vault/v1/connect/${TOKEN}/deny"Authorization
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 对象标识符 |
| type | "vault_authorization" | 是 | 对象类型 |
| vault_id | string | 是 | 库 ID |
| status | "pending" / "authorizing" / "completed" / "failed" / "expired" | 是 | 状态 |
| resource | string | 是 | 资源地址 |
| secret_name | string | 是 | 关联的 Secret 名称 |
| connect_url | string | 是 | 交给最终用户打开的确认页，30 分钟内有效、只能使用一次 |
| client_registration | "cimd" / "dcr" / null | 是 | cimd：通过客户端元数据 URL 注册；dcr：动态注册客户端；尚未注册时为 null |
| secret_id | string / null | 是 | 关联的 Secret ID；未关联时为 null |
| error | object / null | 是 | 失败原因 |
| error.code | string | 是 | 稳定的错误码 |
| error.message | string | 是 | 可读的错误说明 |
| expires_at | date-time | 是 | 过期时间 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
ReturnUrls
| 字段 | 类型 / 枚举 | 必填 | 说明 |
|---|---|---|---|
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |