<span id="读取当前主体与iam上下文"></span>

# Read the current principal and IAM context

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

`POST /user/info` reads the current principal, role selection context, and capability summary used by App Shell. It uses objects and envelopes distinct from /auth/me browser sessions, /account/detail account profiles, and independent /iam/me/roles and capabilities APIs.

<span id="调用前准备"></span>

## Before you call this API

Set `MOI_ENDPOINT` to the product API prefix `https://api.moi.matrixorigin.cn/v5`; use the corresponding product API URL for a dedicated deployment.

Requires product identity, a target workspace, and server-validated role context. SDKs select explicit candidates through workspace-scoped typed mappings; CLI uses configured mappings. Raw HTTP headers are also merely unvalidated candidates and do not grant permissions. A nonready context may still return 200 for interface recovery. Do not continue using the old role's capability results.

<span id="请求"></span>

## Request

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

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

:::::
:::::{tab-item} Parameters

No business request body. The handler reads no user/role/workspace from the body and consumes no capability_id filter; that belongs to the independent GET capabilities API. The authenticated principal and candidates come from the established call context.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| data.user / role | string | Display user and role names; local names do not determine allow. |
| data.is_admin | boolean | Display administrator marker; not a substitute for Core capabilities or the single effective role. |
| data.user_info | object | id/name/status/reserved. id is the principal reference used by this request; do not interchange it unconditionally by name with /auth/me.uid, UC subject, or detail id. |
| data.iam_context | object | Compact role context; see [shared contract](bootstrap-context.md). |
| data.iam_capabilities | object | Compact capability results and request_id/trace_id; see [shared contract](bootstrap-context.md). |
| data.iam_snapshot_version | string | Server state fingerprint for recognizing refreshes, not a write CAS version or permission ticket. |

First check iam_context.role_context_status=ready, then use allowed and all_resources/resource_ids to determine operation scope. Display fields is_admin, role, and reserved do not replace actual request authorization.

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

<span id="错误与恢复"></span>

## Errors and recovery

| HTTP | code | Current branch |
| --- | --- | --- |
| 400 | INVALID_ARGUMENT | Invalid workspace/current principal or call-context input. |
| 404 | USER_NOT_FOUND | Membership-not-found mapping; revoked membership has a separate 403. |
| 403 | ErrWorkspaceMembershipRevoked | Revoked/disabled membership, using the localized IAM error envelope. |
| 403 | IAM_ERROR_CODE_PERMISSION_DENIED | Permission denied. |
| 503 | IAM_ERROR_CODE_CORE_AUTHORIZE_UNAVAILABLE | Core, authorization snapshot, or current-role dependencies unavailable. |
| 500 | INTERNAL | Fact/projection or internal error. |

Ordinary membership errors include data:null; revoked membership uses IAM errors. Not every failure has an identical data shape. Identity middleware may reject requests earlier. Missing default roles, invalid candidates, or disabled roles may appear as nonready states in a successful response. HTTP 200 does not establish usable authorization.
