Create a 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": {} }'

Encrypt and store one Workspace Connection. Use Idempotency-Key so an ambiguous create can be recovered safely. Organization-scoped mutation requires the organization owner.

Authorizations

• creatorBearerAuth
• creatorSessionCookieAuth

Parameters

Path Parameters

app_slug

required

string

Header Parameters

Idempotency-Key

string

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

Stable create mutation identifier used for exact replay and recovery.

Request Body^required

Media typeapplication/json

One of: discriminator: provider

object

object

display_name

required

string

>= 1 characters <= 128 characters

provider

required

string

Allowed values: web_search

credential_mode

required

string

Allowed values: x_api_key

secret

required

A non-empty, well-formed UTF-16 write-only credential of at most 65,536 UTF-8 encoded bytes. It is encrypted by the service and never returned.

string

>= 1 characters <= 65536 characters

configuration

Bounded non-secret provider configuration.

object

key

additional properties

any

object

object

display_name

required

string

>= 1 characters <= 128 characters

provider

required

string

Allowed values: mcp

credential_mode

required

string

Allowed values: bearer x_api_key

secret

required

A non-empty, well-formed UTF-16 write-only credential of at most 65,536 UTF-8 encoded bytes. It is encrypted by the service and never returned.

string

>= 1 characters <= 65536 characters

endpoint

required

Exact canonical HTTPS URL serialization accepted unchanged by the Runtime URL parser. Authority and a slash-prefixed path are required; user information, query parameters, fragments, and whitespace are forbidden.

string format: uri

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

configuration

Bounded non-secret provider configuration.

object

key

additional properties

any

Responses

201

The Connection was created. The submitted credential is not returned.

Media typeapplication/json

object

connection

required

Redacted Workspace Connection state. It contains a server-managed reference and sanitized capabilities, never private credential material.

object

id

required

string

credential_ref

required

Opaque server-managed reference used by materialized v1 Tool bindings.

string

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

scope

required

object

kind

required

string

Allowed values: creator organization

id

required

string

provider

required

string

Allowed values: web_search mcp

display_name

required

string

endpoint

required

string format: uri

nullable

configuration

required

Bounded provider configuration with credential-shaped fields forbidden.

object

key

additional properties

any

credential_mode

required

string

Allowed values: bearer x_api_key

cached_capabilities

required

Sanitized bounded capability marker or MCP Tool manifest from the last successful test.

object

key

additional properties

any

status

required

string

Allowed values: active error deleted

last_tested_at

required

string format: date-time

nullable

last_error_code

required

string

nullable

Allowed values: workspace_connection_test_required workspace_connection_auth_unavailable workspace_connection_provider_unavailable

created_at

required

string format: date-time

updated_at

required

string format: date-time

rotated_at

required

string format: date-time

nullable

deleted_at

required

string format: date-time

nullable

Example

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

400

The bounded request or Connection fields are invalid.

Media typeapplication/json

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: 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

Example

{
  "code": "workspace_connection_failed"
}

401

The creator session is missing, invalid, expired, or does not have a verified email.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: creator_session_required creator_email_unverified creator_session_invalid creator_session_expired

Example

{
  "code": "creator_session_required"
}

403

A public Agent Business runtime credential cannot access creator control-plane APIs.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: runtime_token_not_allowed

Example

{
  "code": "runtime_token_not_allowed"
}

404

The Workflow or mutable Connection scope is unavailable to this creator.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: application_unavailable

object

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: 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

Example

{
  "code": "application_unavailable"
}

409

The Agent Business is not a Workflow, the creator identity conflicts, the idempotency key conflicts, the scope is at capacity, or a concurrent mutation won.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: application_not_workflow

object

object

error

required

string

code

required

string

Allowed values: creator_identity_conflict

object

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: 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

Example

{
  "code": "application_not_workflow"
}

413

The bounded request exceeds 96 KiB.

Media typeapplication/json

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: 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

Example

{
  "code": "workspace_connection_failed"
}

500

An unexpected Workspace Connection failure was sanitized before returning it.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: workspace_connection_failed

Example

{
  "code": "workspace_connection_failed"
}

502

The configured creator identity service failed while verifying the session.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: creator_session_verification_failed

Example

{
  "code": "creator_session_verification_failed"
}

503

Creator auth, control-plane storage, mutations, encryption, or authoritative Connection storage is unavailable.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: creator_auth_provider_invalid creator_session_not_configured creator_control_storage_not_configured

object

object

error

required

string

code

required

string

Allowed values: workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_test_state_unavailable

Example

{
  "code": "creator_auth_provider_invalid"
}