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.

Create a connection

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

{"release_namespace":"system","release_id":"<发布ID>","requirement":"<连接要求键>","profile":"<配置键>","name":"我的插件账号"}
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.

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 and the CLI guide Messaging Channels and Plugins.

Last updated on