<span id="准备原生cli产品身份"></span>

# Bootstrap product identity for a native CLI

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

Use a UC native-login access token to prepare product identity and query or start default workspace provisioning. This request writes identity mappings and may submit a workspace creation job.

```text
POST https://api.moi.matrixorigin.cn/v5/auth/cli/bootstrap
```

<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.

Use an access token issued by UC native login. Supply only one Authorization: Bearer, without session Cookies or X-API-Key. Execute only where identity initialization and default workspace creation are permitted.

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

## Request

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

```bash
curl --fail-with-body -X POST "$MOI_ENDPOINT/auth/cli/bootstrap" \
  -H "Authorization: Bearer $UC_ACCESS_TOKEN"
```

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

| Parameter | Location | Required | Description |
| --- | --- | --- | --- |
| Authorization | header | Yes | One Bearer credential. The scheme is case-insensitive. The token must be nonempty, at most 16 KiB, and contain no spaces, carriage returns, newlines, or tabs. |

No business request body. An account bootstrap-native command using X-API-Key is not a valid native login method.

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

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

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "issuer": "https://uc.example.test",
    "subject": "subject-example",
    "session_id": "session-example",
    "principal_id": "principal-example",
    "catalog_user_id": "catalog-user-example",
    "workspaces": [],
    "workspace_initialization": {
      "status": "failed",
      "code": "ErrNativeWorkspacePreparation",
      "message": "示例工作区准备失败"
    }
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| data.issuer / subject / session_id | string | Issuer, subject, and session from the upstream native identity assertion. |
| data.principal_id | string | Product identity ID. |
| data.catalog_user_id | string | Catalog/IAM user mapping ID; not interchangeable with principal_id or subject. |
| data.workspaces | array (objects) | Currently visible workspaces and pending invitation choices. The full nested Workspace object contract remains unverified. |
| workspaces[].invitation_id | string | Invitation choices may include this identifier. PENDING_INVITATION/access_status=pending does not mean an invitation was accepted. |
| data.workspace_initialization | object | Independent provisioning result. Identity success does not guarantee workspace readiness. |
| workspace_initialization.status | string | ready, pending, running, succeeded, or failed. Failure can coexist with outer OK. |
| workspace_initialization.job_id / code / message | string | Returned when populated, for job handoff, failure classification, and messages respectively. |

The current preparation budget is three seconds and does not wait for workspace DDL. An existing joined workspace may return ready; invitation-only choices may still trigger a default workspace job. Preparation errors without JobID may return failed/ErrNativeWorkspacePreparation, as illustrated. Outer OK does not permit workspace operations. Complete job states, polling handoff, and cleanup have not yet passed acceptance testing.

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

<span id="错误响应"></span>

## Error responses

| HTTP | code | Condition |
| --- | --- | --- |
| 400 | ErrMultipleAuthCredentials | Product session Cookies, X-API-Key, or multiple Authorization values mixed in. |
| 401 | ErrNativeSessionInvalid | Invalid credential format or upstream native credentials. |
| 403 | ErrUserNotSynced | Credential principal has not been mapped. |
| 503 | ErrNativeSessionUnavailable | Upstream identity service unavailable. |
| 503 | ErrNativeProvisioningFailed | Ambiguous mappings or identity preparation failure. |
| 500 | ErrServer | Localization or DTO conversion failure. |

Error messages are localized. Do not retry by matching a fixed msg. For workspace preparation failure under outer HTTP 200, inspect the provisioning object in the success response.
