<span id="提交插件账号凭据"></span>

# Submit plugin account credentials

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

Validate and save credentials required by the selected plugin profile and return nonsensitive authorization state.

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

<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` and `connection_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/$CONNECTION_ID/secret" \
  -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" --slurpfile PLUGIN_SECRET_FIELDS_FILE "$PLUGIN_SECRET_FIELDS_FILE" '
{
  "expected_version": $CONNECTION_VERSION,
  "fields": $PLUGIN_SECRET_FIELDS_FILE[0]
}
')"
```

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

For secret or provider_issued drivers. fields must be nonempty. Each value is limited to 65536 bytes and total values to 1 MiB; the whole HTTP JSON request body also has a 1 MiB limit. Read release configuration and the current connection version first. Store required credential fields in the JSON object at $PLUGIN_SECRET_FIELDS_FILE. The service verifies credentials and returns nonsensitive authorization state. Release configuration determines fields and verification URLs; they cannot be overridden here.

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_version` | integer | Yes | Current connection or installation version; must be greater than 0. |
| `fields` | object | Yes | Submit string values using field names declared by the selected profile. Duplicate keys are not allowed. |
| `fields["凭据字段"]` | string | Conditional | Follow required conditions in profile.fields. Submitted values cannot be empty. |

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": {
    "workspace_id": "workspace_example",
    "connection_id": "connection_example",
    "status": "ready",
    "generation": 1,
    "revision": 1,
    "connection_version": 1
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | 0 on success. |
| `data` | object | Data returned by this operation. |
| `data.workspace_id` | string | Resource fields; see [Shared objects and states](objects.md). |
| `data.connection_id` | 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.generation` | integer | Authorization generation, used as expected_generation during disconnection; may be 0 before authorization. |
| `data.revision` | integer | Resource fields; see [Shared objects and states](objects.md). |
| `data.connection_version` | integer | 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.
