Rotate a Workspace Connection credential

PATCH

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

curl --request PATCH \
  --url https://api.agentaab.com/api/app/example/workflow/connections/example/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "secret": "example" }'

Replace the encrypted credential, clear cached capabilities, and require a new Connection test. The replacement credential is never returned.

Authorizations

• creatorBearerAuth
• creatorSessionCookieAuth

Parameters

Path Parameters

app_slug

required

string

connection_id

required

string

<= 128 characters

Request Body^required

Media typeapplication/json

object

secret

required

A non-empty, well-formed UTF-16 write-only replacement credential of at most 65,536 UTF-8 encoded bytes. It is never returned. Rotation clears cached capabilities and requires a new test.

string

>= 1 characters <= 65536 characters

Example^generated

{
  "secret": "example"
}

Responses

200

The rotated redacted Connection summary in a test-required state.

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 exact replacement body is 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 Connection is missing, deleted, outside the caller’s scope, or not mutable by this caller.

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, or a concurrent Connection 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, decryption, or 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"
}