<span id="检查插件账号授权尝试"></span>

# Check a plugin account authorization attempt

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

Check and advance an authorization attempt for the same plugin account.

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

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

## Before you call this API

Prepare the target workspace ID and a personal access token with resource access and permission for this action. Use actual resource identifiers for path `workspace_id`, `connection_id`, and `attempt_id`. Set `X-Workspace-ID` to the 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/$ATTEMPT_ID/poll" \
  -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
}
')"
```

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

Set $ATTEMPT_ID to the saved nonempty attempt ID. Each call performs one check. Obey poll_after while pending/exchanging and stop at a terminal state. Authorization status determines whether authorization is usable. next_action requires another user action. Recheck when versions change or attempts become superseded or expired; do not automatically start new authorization.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_version` | integer | Yes | Current connection or installation version; must be greater than 0. |

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": "attempt_example",
    "status": "pending",
    "poll_after": 2
  }
}
```

:::::
:::::{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.status` | string | Current state; assess it using this page's conditions and common objects. |
| `data.poll_after` | integer | 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.
