创建 Workspace Connection

POST

/api/app/{app_slug}/workflow/connections/

curl --request POST \
  --url https://api.agentaab.com/api/app/example/workflow/connections/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "display_name": "example", "provider": "web_search", "credential_mode": "x_api_key", "secret": "example", "configuration": {} }'

加密并存储一个 Workspace Connection。使用 Idempotency-Key 可安全恢复结果不明确的创建。组织 Scope 的变更要求组织 Owner 权限。

授权

• creatorBearerAuth
• creatorSessionCookieAuth

参数

路径参数

app_slug

必填

string

请求头参数

Idempotency-Key

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/

用于准确重放与恢复的稳定创建 Mutation 标识。

请求体^必填

媒体类型application/json

One of: discriminator: provider

object

object

display_name

必填

string

>= 1 characters <= 128 characters

provider

必填

string

允许的值： web_search

credential_mode

必填

string

允许的值： x_api_key

secret

必填

非空、格式正确的 UTF-16 只写凭据；UTF-8 编码后不超过 65,536 字节。服务会加密该凭据，且绝不会返回。

string

>= 1 characters <= 65536 characters

configuration

有界的非 Secret Provider 配置。

object

key

附加属性

any

object

object

display_name

必填

string

>= 1 characters <= 128 characters

provider

必填

string

允许的值： mcp

credential_mode

必填

string

允许的值： bearer x_api_key

secret

必填

非空、格式正确的 UTF-16 只写凭据；UTF-8 编码后不超过 65,536 字节。服务会加密该凭据，且绝不会返回。

string

>= 1 characters <= 65536 characters

endpoint

必填

Runtime URL 解析器可原样接受的精确规范 HTTPS URL 序列化。必须包含 Authority 与斜杠开头的路径；禁止用户信息、Query 参数、Fragment 和空白字符。

string format: uri

<= 2048 characters /^https://[^\s/?#@]+/[^\s?#]*$/

configuration

有界的非 Secret Provider 配置。

object

key

附加属性

any

响应

201

Connection 已创建。提交的凭据不会返回。

媒体类型application/json

object

connection

必填

脱敏后的 Workspace Connection 状态。它包含服务端管理的引用和脱敏 Capability，绝不包含私有凭据材料。

object

id

必填

string

credential_ref

必填

物化的 v1 Tool 绑定使用的不透明服务端管理引用。

string

/^WORKSPACE_CONNECTION_[A-F0-9]{32}$/

scope

必填

object

kind

必填

string

允许的值： creator organization

id

必填

string

provider

必填

string

允许的值： web_search mcp

display_name

必填

string

endpoint

必填

string format: uri

可为空

configuration

必填

禁止凭据形状字段的有界 Provider 配置。

object

key

附加属性

any

credential_mode

必填

string

允许的值： bearer x_api_key

cached_capabilities

必填

最近一次成功测试产生的脱敏有界 Capability 标记或 MCP Tool Manifest。

object

key

附加属性

any

status

必填

string

允许的值： active error deleted

last_tested_at

必填

string format: date-time

可为空

last_error_code

必填

string

可为空

允许的值： workspace_connection_test_required workspace_connection_auth_unavailable workspace_connection_provider_unavailable

created_at

必填

string format: date-time

updated_at

必填

string format: date-time

rotated_at

必填

string format: date-time

可为空

deleted_at

必填

string format: date-time

可为空

示例

{
  "connection": {
    "scope": {
      "kind": "creator"
    },
    "provider": "web_search",
    "credential_mode": "bearer",
    "status": "active",
    "last_error_code": "workspace_connection_test_required"
  }
}

400

有界请求或 Connection 字段无效。

媒体类型application/json

object

error

必填

string

code

必填

稳定且公开安全的 Workspace Connection 错误标识。

string

允许的值： workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

示例

{
  "code": "workspace_connection_failed"
}

401

创作者 Session 缺失、无效、已过期，或没有经过验证的电子邮件。

媒体类型application/json

object

error

必填

string

code

必填

string

允许的值： creator_session_required creator_email_unverified creator_session_invalid creator_session_expired

示例

{
  "code": "creator_session_required"
}

403

Agent Business 的公开 Runtime 凭据不能访问创作者控制面 API。

媒体类型application/json

object

error

必填

string

code

必填

string

允许的值： runtime_token_not_allowed

示例

{
  "code": "runtime_token_not_allowed"
}

404

此创作者无法访问 Workflow 或可变更的 Connection Scope。

媒体类型application/json

One of:

object

object

error

必填

string

code

必填

string

允许的值： application_unavailable

object

object

error

必填

string

code

必填

稳定且公开安全的 Workspace Connection 错误标识。

string

允许的值： workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

示例

{
  "code": "application_unavailable"
}

409

Agent Business 不是 Workflow、创作者身份冲突、幂等键冲突、Scope 达到容量上限，或并发 Mutation 已先完成。

媒体类型application/json

One of:

object

object

error

必填

string

code

必填

string

允许的值： application_not_workflow

object

object

error

必填

string

code

必填

string

允许的值： creator_identity_conflict

object

object

error

必填

string

code

必填

稳定且公开安全的 Workspace Connection 错误标识。

string

允许的值： workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

示例

{
  "code": "application_not_workflow"
}

413

有界请求超过 96 KiB。

媒体类型application/json

object

error

必填

string

code

必填

稳定且公开安全的 Workspace Connection 错误标识。

string

允许的值： workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

示例

{
  "code": "workspace_connection_failed"
}

500

返回前已清理意外的 Workspace Connection 故障。

媒体类型application/json

object

error

必填

string

code

必填

string

允许的值： workspace_connection_failed

示例

{
  "code": "workspace_connection_failed"
}

502

配置的创作者身份服务在验证 Session 时失败。

媒体类型application/json

object

error

必填

string

code

必填

string

允许的值： creator_session_verification_failed

示例

{
  "code": "creator_session_verification_failed"
}

503

创作者认证、控制面存储、Mutation、加密或权威 Connection 存储不可用。

媒体类型application/json

One of:

object

object

error

必填

string

code

必填

string

允许的值： creator_auth_provider_invalid creator_session_not_configured creator_control_storage_not_configured

object

object

error

必填

string

code

必填

string

允许的值： workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_test_state_unavailable

示例

{
  "code": "creator_auth_provider_invalid"
}