# 一键授权 (/docs/api/native/vault/authorizations)



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

[指南 →](/docs/cloud/services/vault/quickstart)

[基础地址与鉴权](/docs/api/native/vault)

一键授权为支持 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 [#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 | 否 |

```bash
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。 |

### 响应 [#响应-1]

#### HTTP 200 [#http-200-1]

**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 | 是 | 更新时间 |

### 错误响应 [#错误响应-1]

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

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |

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

## 读取回跳地址 [#读取回跳地址]

`GET /vault/v1/settings/return_urls`

### 响应 [#响应-2]

#### HTTP 200 [#http-200-2]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |

### 错误响应 [#错误响应-2]

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

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

## 设置回跳地址 [#设置回跳地址]

`PUT /vault/v1/settings/return_urls`

### 请求体 [#请求体-1]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |

### 响应 [#响应-3]

#### HTTP 200 [#http-200-3]

**application/json**

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |

### 错误响应 [#错误响应-3]

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

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

```bash
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 | 服务方声明的授权服务器地址。 |

### 响应 [#响应-4]

#### HTTP 200 [#http-200-4]

**text/html**

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

#### HTTP 302 [#http-302]

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

### 错误响应 [#错误响应-4]

| 错误码 | 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 结果页。

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

## OAuth 客户端元数据 [#oauth-客户端元数据]

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

### 响应 [#响应-5]

#### HTTP 200 [#http-200-5]

**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"[] | 否 | 支持的授权响应类型 |

### 错误响应 [#错误响应-5]

没有额外的领域错误。

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

## 授权确认页 [#授权确认页]

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

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| token | path | connect_url 中的一次性令牌。 |

### 响应 [#响应-6]

#### HTTP 200 [#http-200-6]

**text/html**

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

#### HTTP 410 [#http-410]

**text/html**

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

### 错误响应 [#错误响应-6]

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |

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

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

## 继续授权 [#继续授权]

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

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| token | path | connect_url 中的一次性令牌。 |

### 响应 [#响应-7]

#### HTTP 302 [#http-302-1]

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

### 错误响应 [#错误响应-7]

| 错误码 | 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 | 否 |

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

## 拒绝授权 [#拒绝授权]

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

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| token | path | connect_url 中的一次性令牌。 |

### 响应 [#响应-8]

#### HTTP 200 [#http-200-7]

**text/html**

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

#### HTTP 302 [#http-302-2]

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

### 错误响应 [#错误响应-8]

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |

设置了 return\_url 时返回 302；未设置时返回 HTTP 200 结果页。

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

## Authorization [#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 [#returnurls]

| 字段 | 类型 / 枚举 | 必填 | 说明 |
| --- | --- | --- | --- |
| urls | string[] | 是 | https 地址，精确匹配，最多 10 个 |