---
title: "接口参考 - QiSSO"
description: "查阅正式协议端点、请求格式、响应字段、认证方式与受信接口边界。"
canonical_url: "https://docs.mcent.cn/qisso/api-reference"
---
# 接口参考 - QiSSO

> 查阅正式协议端点、请求格式、响应字段、认证方式与受信接口边界。

正式账号地址为 `https://account.mcent.cn`，Issuer 为 `https://account.mcent.cn/realms/mcent`。OIDC 客户端启动时仍从 Discovery 读取端点，不把此表当作替代元数据的永久硬编码配置。

## 协议端点

以下为正式 Discovery 当前提供的路径：

<table>
<thead>
  <tr>
    <th>
      能力
    </th>
    
    <th>
      方法
    </th>
    
    <th>
      路径
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Discovery
    </td>
    
    <td>
      GET
    </td>
    
    <td>
      <code>
        /realms/mcent/.well-known/openid-configuration
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      授权
    </td>
    
    <td>
      GET
    </td>
    
    <td>
      <code>
        /realms/mcent/oauth2/authorize
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      换码 / 刷新 / 服务令牌
    </td>
    
    <td>
      POST
    </td>
    
    <td>
      <code>
        /realms/mcent/oauth2/token
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      UserInfo
    </td>
    
    <td>
      GET / POST
    </td>
    
    <td>
      <code>
        /realms/mcent/oauth2/userinfo
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      公钥集
    </td>
    
    <td>
      GET
    </td>
    
    <td>
      <code>
        /realms/mcent/jwks
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      标准令牌撤销
    </td>
    
    <td>
      POST
    </td>
    
    <td>
      <code>
        /realms/mcent/oauth2/revoke
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      标准令牌内省
    </td>
    
    <td>
      POST
    </td>
    
    <td>
      <code>
        /realms/mcent/oauth2/introspect
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      统一退出
    </td>
    
    <td>
      GET
    </td>
    
    <td>
      <code>
        /realms/mcent/oauth2/end-session
      </code>
    </td>
  </tr>
</tbody>
</table>

端点被发现不代表任意客户端都可以使用它的全部能力。应用注册、客户端认证、令牌归属与服务端策略继续生效。标准 `/oauth2/introspect` 与下文专用服务内省不是同一个接口。

## 授权请求

必需参数及含义见 [OIDC 登录](https://docs.mcent.cn/qisso/oidc-login)。QiSSO 使用 `response_type=code` 与 `code_challenge_method=S256`。当前交互流程支持普通 query 回调，也实现 `response_mode=form_post`；不支持的模式会被拒绝。

使用 `form_post` 时，回调路由必须接收 `application/x-www-form-urlencoded` 的 POST 请求，且事务 Cookie 策略允许浏览器在该返回场景携带 Cookie。不能把只接收 GET 的回调直接切换为 form_post。

## Token 请求

三种请求均使用 `Content-Type: application/x-www-form-urlencoded`：

<table>
<thead>
  <tr>
    <th>
      <code>
        grant_type
      </code>
    </th>
    
    <th>
      其他主要字段
    </th>
    
    <th>
      条件
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        authorization_code
      </code>
    </td>
    
    <td>
      <code>
        code
      </code>
      
      、<code>
        redirect_uri
      </code>
      
      、<code>
        code_verifier
      </code>
    </td>
    
    <td>
      同一登录事务的回调与 S256 verifier
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refresh_token
      </code>
    </td>
    
    <td>
      <code>
        refresh_token
      </code>
    </td>
    
    <td>
      应用允许刷新且原授权获得对应 scope
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        client_credentials
      </code>
    </td>
    
    <td>
      <code>
        scope
      </code>
    </td>
    
    <td>
      机密客户端，使用获准的服务 scope
    </td>
  </tr>
</tbody>
</table>

机密客户端使用登记的 `client_secret_basic` 或 `client_secret_post`；公共客户端提交 `client_id`、不提交 Secret。管理端当前支持的认证选项是 `none`、Basic 与 Post；不要因为 Discovery 底层元数据列出其他认证方式，就推断管理端已经为你的应用启用它。

成功响应结构示意：

```json
{
  "access_token": "<server_only_access_token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email",
  "id_token": "<user_login_id_token>",
  "refresh_token": "<optional_refresh_token>"
}
```

`id_token` 只用于用户 OIDC 流程；`refresh_token` 仅在适用流程中返回，不应将示例所有字段设为必填。机器流程不创建用户会话。不要假设 `expires_in` 始终为示例值，也不要根据字符串外形推断令牌已通过校验。

OAuth 错误通常返回稳定 `error` 与可读 `error_description`，例如 `invalid_client`、`invalid_grant`、`invalid_scope`、`unauthorized_client`。日志只记录错误类别与请求阶段，不记录请求凭据或令牌。

## UserInfo

```http
GET /realms/mcent/oauth2/userinfo
Authorization: Bearer <user_access_token>
```

使用用户 Access Token，不能使用 ID Token 或机器服务令牌代替。读取返回的 `sub` 并与已验证 ID Token 保持一致，资料字段按获准 scope 和实际返回处理。

## 标准令牌撤销

使用元数据中的 `revocation_endpoint` 及登记的客户端认证方式，表单字段为 `token`，可按适用类型提供 `token_type_hint`。这用于撤销令牌，不等同于用户撤销整个应用授权关系，也不能替代业务会话删除。

业务端不把标准内省作为任意用户、任意客户端的通用查询接口；资源服务应先约定受众、令牌类型、凭据和允许的调用范围。

## 统一退出请求

当前退出端点接收 GET，`id_token_hint` 为必需字段，`client_id`、`post_logout_redirect_uri` 和 `state` 按场景填写。退出回跳必须在应用中登记；完整边界见[会话与退出](https://docs.mcent.cn/qisso/sessions-and-logout)。不要把其他服务的 POST 退出调用直接套用到这里。

## 受信授权重新核验

```http
GET /api/v1/service/authorization/users/<url_encoded_sub>
Authorization: Bearer <service_access_token>
```

需要 `users:read`、有效机器令牌与调用方允许名单。成功字段为 `sub`、`roles`、`permissions`、`authz_ver`、`checked_at`，请求 ID 最长 191 字符且不能含控制字符。详见[服务端调用](https://docs.mcent.cn/qisso/server-integration)。

受信接口使用 HTTP 状态及结构化错误数据，读取方式与 OAuth 端点不同。示意：

```json
{
  "statusCode": 403,
  "statusMessage": "APPLICATION_AUTHORIZATION_REVOKED",
  "data": { "code": "APPLICATION_AUTHORIZATION_REVOKED" }
}
```

<table>
<thead>
  <tr>
    <th>
      状态
    </th>
    
    <th>
      常见错误
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      <code>
        INVALID_USER_ID
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      <code>
        INVALID_TOKEN
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      <code>
        INSUFFICIENT_SCOPE
      </code>
      
      、<code>
        ACCOUNT_NOT_ACTIVE
      </code>
      
      、<code>
        APPLICATION_AUTHORIZATION_REVOKED
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      <code>
        USER_NOT_FOUND
      </code>
    </td>
  </tr>
</tbody>
</table>

## 受信账号资料

<table>
<thead>
  <tr>
    <th>
      方法 / 路径
    </th>
    
    <th>
      Scope
    </th>
    
    <th>
      主要请求字段
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/v1/service/account/summary
      </code>
    </td>
    
    <td>
      <code>
        account.profile.read
      </code>
    </td>
    
    <td>
      <code>
        X-QiSvc-User-Id
      </code>
      
      ，可选 <code>
        X-QiSvc-Session-Id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PATCH /api/v1/service/account/profile
      </code>
    </td>
    
    <td>
      <code>
        account.profile.write
      </code>
    </td>
    
    <td>
      <code>
        X-QiSvc-User-Id
      </code>
      
      ，JSON <code>
        { "name": "显示名称" }
      </code>
    </td>
  </tr>
</tbody>
</table>

更新的 `name` 去除首尾空白后为 1–100 字符，接口拒绝未知字段。用户 ID 由 BFF 从已验证会话提取，不允许浏览器自行指定目标账号。摘要结构属于受信账号能力，不在通用登录回调中调用它来替代 UserInfo。

## 嵌入式接口

初始化、密码、TOTP、备用码四个端点的字段、状态与错误见[嵌入式登录](https://docs.mcent.cn/qisso/embedded-login)。它们使用 JSON、精确 Origin 和 credentialed CORS；不能套用 token 端点的表单格式，也不能以 Basic Secret 代替浏览器 CSRF。

## 专用资源服务内省

`POST /api/v1/service/tokens/introspect` 只用于既有 QiLicense 资源服务身份，使用 Basic 认证与表单 `token`，可选 `token_type_hint=access_token`。只接受规定的两个字段，表单请求体最多 2048 字符，单个 token 最长 512 字符。

有效机器令牌返回 `active: true`、`permissions`、`exp`、`client_id`、`sub: null`；不符合策略时返回 `{ "active": false }`。资源服务凭据错误为 401，非表单为 415，不支持的 hint 或额外字段为 400。新应用不能将其用作用户会话检查。


## Sitemap

See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.