<span id="连接插件账号"></span>

# Connect a plugin account

Create a connection required by a plugin, complete OAuth and bind it to an installation. Configure credentials and endpoint using [API call basics](../../api-call-basics.md).

<span id="创建连接"></span>

## Create a connection

Select a plugin release and inspect its connection requirements and profiles. Reuse an applicable existing connection. Otherwise prepare `connection.json`:

```json
{"release_namespace":"system","release_id":"<发布ID>","requirement":"<连接要求键>","profile":"<配置键>","name":"我的插件账号"}
```

```shell
curl -X POST "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/plugin-connections" \
  -H "X-API-Key: $PRODUCT_API_KEY" -H "X-Workspace-ID: $WORKSPACE_ID" -H 'Content-Type: application/json' \
  --data-binary @connection.json
```

Preserve the connection `id` and `version` in the business response. OAuth settings come from the release.

<span id="授权与回读"></span>

## Authorize and inspect

All following paths are relative to the Product API Endpoint. `id` identifies the same connection. When an attempt ID exists, retain `attempt_id` returned by authorization. Authorization state does not guarantee this field is returned.

| Method and path | Input and result |
| --- | --- |
| `GET /workspaces/{workspace_id}/plugin-releases?namespace=system` | Select a visible release; use `namespace=workspace` for workspace releases. |
| `GET /workspaces/{workspace_id}/plugin-releases/{release_id}` | Read requirements, including the release namespace query parameter. |
| `GET /workspaces/{workspace_id}/plugin-connections` | Select an existing connection. |
| `GET /workspaces/{workspace_id}/plugin-connections/{id}` | Current connection and version. |
| `GET /workspaces/{workspace_id}/plugin-connections/{id}/authorization` | Authorization state, connection version, and authorization `generation`. Some managed-session states also include the current attempt ID. |
| `POST /workspaces/{workspace_id}/plugin-connections/{id}/oauth` | JSON `expected_version` and `initiator:"external"`; browser or device handoff. |
| `POST /workspaces/{workspace_id}/plugin-connections/{id}/oauth/{attempt_id}/poll` | JSON `expected_version`; one check with status and wait interval. |
| `POST /workspaces/{workspace_id}/plugin-connections/{id}/disconnect` | JSON `expected_generation` from authorization status; inspect again afterward. |

Continue according to `grant`. `browser_handoff` opens a product browser page for authorization; `attempt_id` is empty in that response. Open `authorization_url`, then reread authorization state. Do not poll with an empty ID. If `device_code`, `managed_session`, or another mode returns a valid attempt ID, retain it. Use `user_code` when required and honor `poll_after` and the total waiting limit.

After interruption, use the saved attempt ID together with current status. An absent `attempt_id` in status does not prove that the original attempt expired. If the connection version changes, stop using the old attempt and review the current connection and authorization; do not reuse that attempt with a replacement version. Display names are not authorization identifiers.

After account authorization, bind the connection and authorization profile to the corresponding plugin installation connection requirement, then read the installation result. For actual invocation examples, see the SDK guide [Connect Plugin Accounts](../../../sdk/ai-studio/智能体/连接插件账号.md) and the CLI guide [Messaging Channels and Plugins](../../../cli/tasks/channels-plugins.md#cli-agent-plugin-releases).
