# 获取服务授权Schema

`POST` `/api/agent/finx/getAuthSchema`

返回结构化的授权字段描述，前端据此渲染授权配置表单，API 调用方据此确定要提交哪些凭证字段。

**与 saveAuthCredential 的对应关系**：响应中的 fields[].key 就是 saveAuthCredential 的 credentials 里要填的 key，命名规则为：`credential`（API_KEY / BEARER / BASIC 的主凭证）、`customHeaders.<请求头名>`（CUSTOM）、`queryParams.<参数名>`（URL 参数，可与任意类型叠加）；不在该列表内的 key 会被拒绝。

**其余响应说明**：authType 为鉴权类型（注意：创建/编辑服务时请求体里的键名是 auth.type）；configured 表示该字段是否已配置，maskedValue 为脱敏后的当前值；guidance 为该服务的凭证获取指引（纯文本/Markdown 片段，空字符串表示无指引），建议非空时在授权表单顶部渲染；authScope=AGENT 的 agent 级授权表单同样返回该字段。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 是 | 智能体ID |
| serviceName | string | 是 | 服务标识名，取 listServices 返回的服务名。响应的 fields[].key 就是后续调用 saveAuthCredential 时 credentials 里要填的 key，两者必须一致，不在该列表内的 key 会被拒绝 |
| toolName | string | 否 | 工具标识名。不传（null）时查服务级授权要求（最常用）；仅当需要查看某个使用独立凭证的工具时才传工具名 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | FinxAuthSchemaResult | 响应数据 |
|     serviceName | string | - |
|     toolName | string | - |
|     authType | string | - |
|     authTypeDescription | string | - |
|     requireUserProvided | boolean | - |
|     fields | array | - |
|         key | string | - |
|         displayName | string | - |
|         inputType | string | - |
|         description | string | - |
|         required | boolean | - |
|         configured | boolean | - |
|         maskedValue | string | - |
|     complete | boolean | - |
|     credentialSource | string | - |
|     guidance | string | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |