<span id="发起插件账号授权"></span>

# Start plugin account authorization

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

Return a browser handoff or authorization action for a plugin account.

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/plugin-connections/{connection_id}/oauth
```

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

## Before you call this API

Prepare the target workspace ID and a personal access token with access to the resources and permission for this action. Use actual resource identifiers for `workspace_id` and `connection_id` in the path. Also set `X-Workspace-ID` to that workspace ID. The example uses `jq` to construct JSON; install it first. See [common objects and inputs](objects.md#input-identifiers) for environment variable sources.

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

## Request body

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/plugin-connections/$CONNECTION_ID/oauth" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --argjson CONNECTION_VERSION "$CONNECTION_VERSION" '
{
  "expected_version": $CONNECTION_VERSION,
  "initiator": "external"
}
')"
```

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

Handle the response for the grant type. Starting an authorization-code profile with external returns browser_handoff and an empty attempt ID. Open the product browser page, then reread the status. An external client must not impersonate browser to bypass browser proof. Continue device authorization and managed sessions using the nonempty attempt_id and poll_after returned.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_version` | integer | Yes | Current connection or installation version; must be greater than 0. |
| `initiator` | string | Conditionally required | Authorization-code profiles use external or browser. External SDK/CLI clients choose external. |
| `expected_actor_id` | string | No | Checks the current account for browser handoff; if supplied, must match the caller. |
| `runtime_context_id` | string | No | Supply the actual context ID to associate an existing interaction; do not invent one. |

JSON objects reject unknown fields, duplicate keys, and multiple consecutive objects. The entire request body must not exceed 1 MiB.

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

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

## Successful response

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

```json
{
  "code": 0,
  "data": {
    "attempt_id": "",
    "grant": "browser_handoff",
    "authorization_url": "https://console.example.invalid/authorization",
    "expires_at": "2026-11-11T00:10:00Z"
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | 0 on success. |
| `data` | object | Data returned by this action. |
| `data.attempt_id` | string | Authorization attempt ID; empty for browser_handoff. |
| `data.grant` | string | Resource fields; see [common objects and states](objects.md). |
| `data.authorization_url` | string | Open the user authorization page for the grant type. |
| `data.expires_at` | string | Resource fields; see [common objects and states](objects.md). |

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

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

## Error responses

Handle business errors with numeric `code`, `message`, and `details.reason` separately from authorization-layer errors with string codes. See [errors and states](objects.md#error-responses). On state or version conflicts, read the current resource before changing identifiers or retrying writes.
