Plugin objects and states

Plugin releases, installations, account connections, and authorizations maintain separate identifiers and versions. Account connections store nonsensitive configuration; credentials are submitted through separate operations.

Input identifiers

Example variable

Source

AI_STUDIO_API_KEY、WORKSPACE_ID

Personal access token and target Workspace for the current environment.

RELEASE_NAMESPACE

Choose system or workspace. Use the same choice for release details/lists and connection/installation creation.

RELEASE_ID

items[].id from the plugin release list, formatted as pr_ followed by 64 hexadecimal characters.

CONNECTION_REQUIREMENT、CONNECTION_PROFILE

A connections.requirements key from release details and a key in that requirement’s profiles.

CONNECTION_ID、CONNECTION_VERSION

id and version from connection creation or details. Recheck authorization attempts when the version changes.

ATTEMPT_ID

Nonempty attempt_id returned by an authorization operation. browser_handoff provides no pollable attempt ID.

GENERATION

generation from the latest authorization state, used for disconnection.

INSTALLATION_ID、INSTALLATION_VERSION

id and version from an installation response or details.

PLUGIN_BINDINGS_FILE

JSON object file storing complete connection_id/profile/executor_id bindings by requirement key.

PLUGIN_SECRET_FIELDS_FILE

JSON object file storing credential strings according to the selected profile’s field declarations. Do not log its contents.

NEXT_OFFSET

Previous offset plus current items count. Continue only while less than total.

NEXT_CURSOR

next_cursor from the search response. Continue only when has_more is true.

PLUGIN_QUERY

Capability name or description text to search for.

CAPABILITY_REF

capabilities[].capability_ref from search; pass its original value to later requests.

Plugin account connections

Field

Type

Description

id

string

Connection ID.

workspace_id

string

Owning Workspace ID.

name

string

Server-generated display value combining provider and connection ID.

description

string

Account description submitted at creation; may be omitted when empty.

status

string

Connection enablement state. Created as active; status updates accept active/disabled.

kind

string

plugin for plugin connections.

endpoint_uri

string

Resource derived from release configuration, not chosen in the creation request.

auth_type

string

Authentication type derived from the selected driver and configuration.

owner_user_id

string

Connection owner, returned to identify ownership.

visibility

string

Created account connections are private.

config

object

Nonsensitive release and authorization configuration bindings.

config.provider

string

Provider.

config.auth_profile

string

Authorization profile key.

config.profile_digest

string

Authorization profile digest, used to verify matching.

config.release_workspace_id

string

Workspace owning the release.

config.release_id

string

Release ID.

config.requirement

string

Requirement key.

config.executor_id

string

Actual executor ID for a managed session, used for later installation binding when present.

version

integer

Connection metadata version, used as expected_version.

created_at

string

Creation time in RFC 3339 format.

updated_at

string

Update time in RFC 3339 format.

capabilities

string (array of strings)

Optional capability list.

labels

object

Optional labels.

annotations

object

Optional annotations.

metadata

object

Optional extension information.

last_test_status

string

Latest test status.

last_tested_at

string

Latest test time.

last_test_error

string

Latest test error summary.

created_by

string

Creating account.

updated_by

string

Account that last modified the resource.

Account authorization state is returned by a separate API. active does not mean OAuth is complete. A credential-free none profile does not enter OAuth or credential submission flows.

Account authorization state

Field

Type

Description

workspace_id

string

Workspace ID owning the authorization.

connection_id

string

Account connection ID.

connection_version

integer

Connection version associated with the authorization.

status

string

Current authorization state.

generation

integer

Authorization generation. Read the latest value before disconnecting.

revision

integer

Credential revision within the same generation.

external_subject

string

Confirmed provider account identifier, returned when present.

account_display_name

string

Display name for some managed accounts, returned when present; not an authorization identifier.

attempt_id

string

Attempt ID returned by some ongoing managed sessions. Do not assume it can recover every OAuth flow.

status

Caller action

not_connected

No authorization record yet; generation and revision are 0. Initiate the applicable authorization for the configuration.

pending

Continue user authorization according to the action, checking the original attempt ID when needed.

ready

Authorization is ready; actual calls remain subject to current permissions, configuration, and credential validity.

refreshing

OAuth credentials are refreshing. Do not copy or replace them yourself.

retiring、expiring

The managed session is being cleaned up or expiring; do not treat it as ready.

reauthorize、disconnected

Authorize again using current configuration. Local disconnection does not guarantee provider revocation is complete.

Authorization actions and check results

Action field

Type

Description

grant

string

browser_handoff, authorization_code, device_code, or managed_session.

attempt_id

string

Specific attempt ID; an empty string for browser handoff.

authorization_url

string

User action page returned by the current branch.

user_code

string

Returned when device authorization requires it.

poll_after

integer

Seconds to wait before checking again, when applicable.

expires_at

string

Expiration time of the current action.

Initiating an authorization-code profile through external returns browser_handoff. After signing into the product in a browser, the browser starts the actual authorization-code flow and retains the security proof Cookie. Browser proof is not passed through external clients.

Check result field

Type

Description

attempt_id

string

Original attempt ID being checked.

status

string

pending/exchanging means keep waiting. succeeded/failed/denied/expired/superseded are terminal attempt states.

reason

string

Failure or state reason, returned when present.

poll_after

integer

Seconds to wait before the next check, when applicable.

next_action

object

A new authorization action when further user interaction is required.

Read account authorization state after a successful check. Without an attempt ID, do not construct a polling path or repeatedly initiate authorization in place of querying state.

Plugin releases

Field

Type

Description

id

string

Release ID.

workspace_id

string

Workspace ID owning the release; requests select it with namespace.

registry

string

Registry source.

publisher

string

Publisher.

name

string

Plugin name.

version

string

Version text declared by the plugin, distinct from integer installation/connection versions.

digest

string

Immutable release digest.

description

string

Release description.

display_name

string

Optional localized name.

display_description

string

Optional localized description.

published_by

string

Publishing account.

created_at

string

Publication time.

Release details also include manifest, connections, profile_digests, servers, operations, and skills. manifest stores the package name, version, description, optional author/homepage/repository/license/keywords, and extensions.

Connection requirement field

Type

Description

connections.requirements["要求键"].provider

string

Account provider.

connections.requirements["要求键"].optional

boolean

Whether the requirement is optional, returned when present.

connections.requirements["要求键"].profiles

object

Map of selectable authorization profiles.

connections.requirements["要求键"].profiles["配置键"].driver

string

none/secret/oauth/provider_issued/managed_session。

connections.requirements["要求键"].profiles["配置键"].resource

string

Fixed account resource.

connections.requirements["要求键"].profiles["配置键"].fields

object

Credential field declarations, including label/secret/required/multiline.

connections.requirements["要求键"].profiles["配置键"].oauth

object

OAuth registration key, authorization method, and scopes.

connections.requirements["要求键"].profiles["配置键"].auth_type

string

Static credential authentication type, when applicable.

connections.requirements["要求键"].profiles["配置键"].verify

object

Credential verification configuration fixed by the release.

connections.requirements["要求键"].profiles["配置键"].injection

object (array of objects)

Credential field injection rules.

connections.requirements["要求键"].profiles["配置键"].client_tls

object

Field mappings for TLS certificates and private keys.

connections.requirements["要求键"].profiles["配置键"].adapter

string

Adapter.

connections.requirements["要求键"].profiles["配置键"].scopes

string (array of strings)

Authorization scopes.

connections.components["能力ID"]

object[]

Each item contains requirement and allowed profiles.

Plugin installations

Field

Type

Description

id

string

Installation ID.

workspace_id

string

Current Workspace ID.

release_workspace_id

string

Workspace owning the release.

release_id

string

Release ID.

release_name

string

Release name.

release_digest

string

Release digest.

owner_user_id

string

Installation owner.

bindings

object

Complete account binding map; updates replace rather than merge it.

bindings["要求键"].connection_id

string

Selected account connection ID.

bindings["要求键"].profile

string

Selected authorization profile key.

bindings["要求键"].executor_id

string

Actual executor ID required by a managed session.

version

integer

Installation version, separate from connection version and authorization generation.

created_at

string

Creation time.

updated_at

string

Update time.

Installations can save empty bindings. Whether a capability can subsequently execute also depends on the selected component’s connection requirements, current authorization, and permissions. Uninstalling does not automatically delete account connections. Remove the corresponding installation bindings before deleting a connection.

Capability search and description

Search returns candidates[], has_more, and optional next_cursor. Each candidate contains source, release, optional installation ID/version, capabilities[], and capabilities_truncated. Each capability consists of capability and a complete capability_ref.

Capability objects contain id/name/description/kind/side_effect/digest. kind is skill/mcp/http/command; side_effect is read/write/execute/dynamic. These descriptions do not replace current permissions or user confirmation for execution.

Description results include the original reference, the capability object, and applicable input_schema, skill_path, mcp_server, or connections. mcp_server fields include type and applicable url/command/args/headers. It is a release declaration, not a tool-probing result for the current account.

Error responses

The plugin business layer uses the following responses. Use stable details.reason values to identify causes; message is localized.

{"code":4,"message":"请求的资源状态已改变","details":{"domain":"moi.agent-plugin","reason":"PLUGIN_STATE_CONFLICT"}}

HTTP status

Common reason

Handling

400

PLUGIN_REQUEST_INVALID

Check fields, namespace, pagination, profiles, and attempt identifiers.

404

PLUGIN_RESOURCE_NOT_FOUND

Check resource identity and visibility.

409

PLUGIN_STATE_CONFLICT、PLUGIN_AUTH_IN_PROGRESS、PLUGIN_REAUTHORIZE_REQUIRED

Read the current connection, installation, or authorization. Do not blindly retry an old request.

410

PLUGIN_AUTH_EXPIRED

The original authorization expired. Review and authorize again.

422

PLUGIN_CREDENTIAL_REJECTED、PLUGIN_CREDENTIAL_NOT_PORTABLE

Check credentials or authorization method. Do not repeatedly publish an invalid result.

502/503

Reasons related to unavailable providers, authorization profiles, executors, or services

Retain safe tracing information and check current state first after recovery.

Authentication or Workspace admission may also return string code, msg, and trace details, such as PLUGIN_ADMISSION_DENIED or Workspace membership errors. Do not force every error into a numeric code or use literal message text as a stable discriminator. No HTTP response does not establish that the operation had no effect.

Last updated on