# View current identity roles

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

View the roles held by the calling identity in the target workspace to confirm the scope of permissions it can use.

```text
GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/iam/me/roles
```

## Preparation before calling

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md) that can access the target workspace and the [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id).

## Request parameters

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

```bash
curl -X GET "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/me/roles" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} Parameter description

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | Target workspace ID. |

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

## Successful response

On success, returns the calling identity's directly assigned roles, default role, explicitly selected candidate role, and effective role. The service does not automatically choose another role if the default role is missing or the candidate is invalid.

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "roles": [],
    "default_role_id": "role-001",
    "default_role_version": 2,
    "explicit_role_id": "",
    "effective_role_id": "role-001",
    "role_context_status": "ready",
    "schema_version": "schema-v1",
    "capability_version": "capability-v1",
    "request_id": "req-001",
    "trace_id": "trace-001"
  }
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.roles` | object array | Roles directly assigned to the current identity and their availability. |
| `data.default_role_id` | string | Current default role ID. |
| `data.default_role_version` | integer | Default role version. |
| `data.explicit_role_id` | string | Explicit role ID specified and validated in the request; empty when none is specified. |
| `data.effective_role_id` | string | Role ID ultimately used for this request. |
| `data.role_context_status` | string | Role context status: `ready`, `default_missing`, `candidate_invalid`, or `role_disabled`. |
| `data.schema_version` | string | Permission schema version. |
| `data.capability_version` | string | Capability projection version. |
| `data.request_id` | string | Request correlation ID. |
| `data.trace_id` | string | Trace ID. |

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

## Error response

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

```json
{
  "code": "ErrIAMCoreUnavailable",
  "msg": "Service temporarily unavailable",
  "data": null
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Error message. |
| `data` | null | — |

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