Skip to main content
PUT
Attach an agent to a connection
Availability: Cloud · Community (self-hosted) · Enterprise (self-hosted)

Authorizations

Authorization
string
header
required

A workspace API key (oc_…) or organization API key (oc_org_…). Workspace-scoped endpoints called with an organization key also need X-Workspace-Id.

Path Parameters

connectionId
string
required
agentId
string
required

Body

application/json

The grant to write. Two forms:

  • {"access": "full"} — every tool the app supports.
  • {"access": "custom", "allow": [...], "ask": [...]} — named tools only. allow runs freely, ask pauses for human approval, everything unnamed is blocked.

Validation laws on custom: the two lists together must name at least one tool (an all-blocked grant is a detach — use DELETE), and a tool can't appear in both lists. Tool ids come from GET /apps/{provider}/permission-definition.

resources is tri-state on both forms: omit it to keep the current scoping, send null to clear it, or send a session-policy object to set it. Setting resources is an Enterprise feature (resource-level access).

access
enum<string>
required
Available options:
full
resources
GitHub repositories · object

Resource scoping for a connection's credential ("Resources"): an object keyed by the provider's resource axis. Exactly one key: repositories (GitHub, owner/repo), folders (Dropbox, absolute paths), or driveFolders (Google Drive, folder-id chains). Lists must be non-empty.

Response

The agent's updated grant set

An agent's full grant set — returned by grant reads and by every grant write.

agentId
string
mode
enum<string>

Always grants on current servers. The all value is wire compatibility with older self-hosted releases; never branch behavior on it.

Available options:
all,
grants
connections
object[]
secrets
object[]