Start plugin account authorization

Return a browser handoff or authorization action for a plugin account.

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

Before you call this API

Prepare the target workspace ID and a personal access token with access to the resources and permission for this action. Use actual resource identifiers for workspace_id and connection_id in the path. Also set X-Workspace-ID to that workspace ID. The example uses jq to construct JSON; install it first. See common objects and inputs for environment variable sources.

Request body

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/plugin-connections/$CONNECTION_ID/oauth" \
  -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,
  "initiator": "external"
}
')"

Handle the response for the grant type. Starting an authorization-code profile with external returns browser_handoff and an empty attempt ID. Open the product browser page, then reread the status. An external client must not impersonate browser to bypass browser proof. Continue device authorization and managed sessions using the nonempty attempt_id and poll_after returned.

Field

Type

Required

Description

expected_version

integer

Yes

Current connection or installation version; must be greater than 0.

initiator

string

Conditionally required

Authorization-code profiles use external or browser. External SDK/CLI clients choose external.

expected_actor_id

string

No

Checks the current account for browser handoff; if supplied, must match the caller.

runtime_context_id

string

No

Supply the actual context ID to associate an existing interaction; do not invent one.

JSON objects reject unknown fields, duplicate keys, and multiple consecutive objects. The entire request body must not exceed 1 MiB.

Successful response

{
  "code": 0,
  "data": {
    "attempt_id": "",
    "grant": "browser_handoff",
    "authorization_url": "https://console.example.invalid/authorization",
    "expires_at": "2026-11-11T00:10:00Z"
  }
}

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.grant

string

Resource fields; see common objects and states.

data.authorization_url

string

Open the user authorization page for the grant type.

data.expires_at

string

Resource fields; see common objects and states.

Error responses

Handle business errors with numeric code, message, and details.reason separately from authorization-layer errors with string codes. See errors and states. On state or version conflicts, read the current resource before changing identifiers or retrying writes.

Last updated on