# 读取当前主体与IAM上下文

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

`POST /user/info`读取App Shell使用的当前主体、角色选择上下文和能力摘要。它与/auth/me浏览器会话、/account/detail账号资料、独立/iam/me/roles及capabilities接口分别使用不同对象和封套。

## 调用前准备

`MOI_ENDPOINT` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

需要产品身份、目标工作区及服务端验证的角色上下文。SDK以workspace-scoped typed mapping选择显式候选，CLI用配置mapping；原始HTTP头也只是未验证候选，不授予权限。非ready上下文仍可返回200用于界面恢复，不能继续使用旧角色的能力结果。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "$MOI_ENDPOINT/user/info" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

没有业务请求体。handler不从body读取用户/角色/工作区，不消费capability_id筛选；该筛选属于独立GET capabilities接口。认证主体和候选来自已建立的调用上下文。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "user": "Example",
    "role": "Data analyst",
    "is_admin": false,
    "user_info": {
      "id": "456",
      "name": "Example",
      "status": "enabled",
      "reserved": false
    },
    "iam_context": {
      "roles": [
        {
          "role_id": "123",
          "role_name": "Data analyst",
          "lifecycle_version": 1,
          "selectable": true,
          "disabled_reason": ""
        }
      ],
      "default_role_id": "123",
      "default_role_version": 2,
      "explicit_role_id": "",
      "effective_role_id": "123",
      "role_context_status": "ready"
    },
    "iam_capabilities": {
      "effective_role_id": "123",
      "request_id": "req-example",
      "trace_id": "trace-example",
      "items": [
        {
          "capability_id": "action.role.create",
          "reason_code": "DENIED",
          "allowed": false,
          "all_resources": false,
          "resource_ids": []
        }
      ]
    },
    "iam_snapshot_version": "1111111111111111111111111111111111111111111111111111111111111111"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.user / role | string | 展示用户及角色名，不按本地名称决定allow |
| data.is_admin | boolean | 展示管理员标记，不替代Core能力/唯一有效角色 |
| data.user_info | object | id/name/status/reserved四项；id是此请求使用的主体引用，不能按名称与/auth/me.uid、UC subject或详情id无条件互换 |
| data.iam_context | object | 精简角色上下文，见[共享合同](bootstrap-context.md) |
| data.iam_capabilities | object | 精简能力结果、request_id/trace_id，见[共享合同](bootstrap-context.md) |
| data.iam_snapshot_version | string | 服务端状态指纹，供识别刷新；不是写入CAS版本或权限票据 |

先判断iam_context.role_context_status=ready，再按allowed和all_resources/resource_ids读取操作范围。展示字段is_admin、role或reserved不能替代实际请求鉴权。

:::::
::::::
:::::::

## 错误与恢复

| HTTP | code | 当前分支 |
| --- | --- | --- |
| 400 | INVALID_ARGUMENT | 工作区/当前主体或调用上下文输入不合法 |
| 404 | USER_NOT_FOUND | 成员未找到映射分支；membership撤销有单独403 |
| 403 | ErrWorkspaceMembershipRevoked | 成员关系被撤销/禁用，使用IAM本地化错误封套 |
| 403 | IAM_ERROR_CODE_PERMISSION_DENIED | 权限拒绝 |
| 503 | IAM_ERROR_CODE_CORE_AUTHORIZE_UNAVAILABLE | Core、授权快照或当前角色依赖不可用 |
| 500 | INTERNAL | 事实/投影或内部错误 |

普通成员错误带data:null，撤销分支走IAM错误，不能强求每种失败都有同一data形状。身份中间件还可能更早拒绝请求。默认角色缺失、候选失效或角色停用可作为成功响应中的非ready状态，不能把HTTP200等同于已取得可用授权。
