Skip to main content
PATCH
Change an integration connection's tool allow-list

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

connectionId
string<uuid>
required

Integration connection id (UUID) as returned by managedAgentsListIntegrationConnections.

Body

application/json

Request body changing the organization tool allow-list of a built-in, GitHub, or Slack integration connection. Validated against the provider's catalog; the connection's state is unchanged and sessions pick the new list up at their next credential refresh.

permission
string
write-only

For a built-in integration, the permission preset the selected tools are checked against: read or write; when omitted, the read preset applies. Omit for native GitHub and Slack: GitHub tools determine token permissions; Slack tools do not change OAuth scopes or thread access.

resources
string[]
write-only

The app's tools the organization's agents may use, by tool name from the catalog. Replaces the connection's allow-list in full; an empty list is refused. Omit to keep the current allow-list, for example to check a built-in integration's tools against another permission preset.

Required array length: 1 - 200 elements

Response

An organization's link to a third-party account, created by installing an integration such as the GitHub App. It holds no secret itself; grant it to an agent so sessions can mint short-lived provider credentials from it.

An organization's link to a third-party account, created by installing an integration such as the GitHub App. It holds no secret itself; grant it to an agent so sessions can mint short-lived provider credentials from it.

connection_id
string
required
read-only

Identifier for this connection (UUID). Server-assigned. Cite it when granting an agent access to the integration.

created_at
string<date-time>
required
read-only

RFC 3339 timestamp of when this record was created. Server-assigned.

external_id
string
required
read-only

The provider's own identifier for the link, which token minting addresses. The installation id for GitHub; the composite {api_app_id}:{team_id} for Slack; the customer service-account email for Google Cloud.

organization_id
string
required
read-only

Organization that owns this record. Resolved from the API key; never accepted from the caller.

provider
string
required
read-only

Stable slug of the third-party integration adapter this connection uses.

state
string
required
read-only

Lifecycle of the connection: pending was registered directly and waits for provider setup (a trust probe or registered OAuth sign-in activates it), active can mint tokens, suspended is restorable at the provider and resolves to no credential, revoked was uninstalled and must be installed again.

updated_at
string<date-time>
required
read-only

RFC 3339 timestamp of the last change to this record. Server-assigned.

account_login
string
read-only

Name of the connected third-party account, e.g. the GitHub org or user login. Cached at install time for display, so no provider call is needed to show it.

account_type
string
read-only

Kind of account that was connected, as the provider reports it, e.g. Organization or User for GitHub and workspace for Slack.

connected_by
string
read-only

User who completed the install, recorded for audit.

lastCheck
object
read-only

Latest completed connection check, with the time it began. Historical evidence, not a guarantee of current availability. Absent until a check has been saved.

mcpTools
string[]
read-only

Native GitHub or Slack MCP tools selected for this organization. A connection with no saved selection gets every supported tool except opt-in tools that delete data, which must be selected explicitly.

mergeAccountLabel
string
read-only

Operator-assigned label distinguishing multiple accounts for one built-in vendor.

permissions
object
read-only

What the provider granted the install, as permission name to access level (e.g. contents: write). Used to narrow a minted token without a provider round trip and to explain why a permission preset is unavailable.

resource_selection
string
read-only

Whether the install covers all of the account's resources or only chosen ones: all or selected. Informational only; the authoritative list stays at the provider.

usage
object
read-only

Runtime usage counts, supplied on the connection list.