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

# Create a plugin account connection

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

Create an account connection according to the plugin release requirements. Complete authorization separately.

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

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

## Before you call this API

Prepare the target workspace ID and a personal access token with access to the resource and the required action privileges. Use actual resource identifiers for `workspace_id` in the path and also set `X-Workspace-ID`. Examples use `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" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg RELEASE_NAMESPACE "$RELEASE_NAMESPACE" --arg RELEASE_ID "$RELEASE_ID" --arg CONNECTION_REQUIREMENT "$CONNECTION_REQUIREMENT" --arg CONNECTION_PROFILE "$CONNECTION_PROFILE" '
{
  "release_namespace": $RELEASE_NAMESPACE,
  "release_id": $RELEASE_ID,
  "requirement": $CONNECTION_REQUIREMENT,
  "profile": $CONNECTION_PROFILE,
  "name": "我的插件账号"
}
')"
```

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

The example uses oauth configuration. Creation saves only the connection and does not authorize the account. managed_session may select an executor supported by the deployment. The server resolves the managed alias to an actual executor. Use the actual value read from the connection for subsequent installation bindings.

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `release_namespace` | string | Yes | system or workspace. |
| `release_id` | string | Yes | Selected release ID from the release list. |
| `requirement` | string | Yes | Requirement key in the release connections.requirements. |
| `profile` | string | Yes | Configuration key in profiles for that requirement. |
| `name` | string | Yes | Caller-supplied account description. The service generates the returned name and saves this value in description. |
| `executor_id` | string | Conditional | Executor identifier required by managed_session profiles; omit or leave empty for other drivers. |

JSON objects reject unknown fields, duplicate keys, and multiple consecutive objects. Total request body size 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": {
    "id": "connection_example",
    "workspace_id": "workspace_example",
    "name": "provider · connection_example",
    "description": "我的插件账号",
    "status": "active",
    "kind": "plugin",
    "endpoint_uri": "https://service.example.invalid",
    "auth_type": "oauth2",
    "visibility": "private",
    "version": 1,
    "created_at": "2026-11-11T00:00:00Z",
    "updated_at": "2026-11-11T00:00:00Z"
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | 0 on success. |
| `data` | object | Data returned by this operation. |
| `data.id` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.workspace_id` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.name` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.description` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.status` | string | Current state; interpret using this page's conditions and common objects. |
| `data.kind` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.endpoint_uri` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.auth_type` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.visibility` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.version` | integer | Current resource version; used as expected_version for writes. |
| `data.created_at` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.updated_at` | string | Resource fields; see [Shared objects and states](objects.md). |

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

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

## Error response

Handle numeric business-error `code`, `message`, and `details.reason` separately from authorization-layer string codes. See [Errors and states](objects.md#error-responses). On a state or version conflict, read the current resource first; do not automatically change identifiers or retry writes.
