> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach an app connection to an agent

> Attaches an app connection to an agent or changes what it may do with it. Pick full access or custom tool lists. It applies immediately.

Grants or updates an agent's access to a connection. Send `full` for every tool, or `custom` with `allow` for tools that run freely and `ask` for tools that pause for approval. See [Agent access](/docs/guides/agent-access.md).

Attach an app connection to an agent, or change what the agent may do with it. Takes effect immediately — there is no draft/publish step.

Send `{"access": "full"}` for every tool the app supports, or `{"access": "custom", "allow": [...], "ask": [...]}` to name tools: `allow` runs freely, `ask` pauses each call for human approval, and everything unnamed is blocked. Add `resources` to scope the credential to specific repositories or folders (Enterprise).

> [!NOTE]
>
> **Availability:** Cloud · Community (self-hosted) · Enterprise (self-hosted)


## OpenAPI

````yaml /openapi.yaml put /agents/{agentId}/grants/connections/{connectionId}
openapi: 3.1.0
info:
  title: Buckle API
  version: '1.0'
  description: >
    The Buckle API manages everything behind the gateway: workspaces, agents and
    what each agent may use (grants), secrets, app connections, organization
    policy, hosted-agent conversations, schedules, memory, skills, Slack
    channels, and the organization's directory.


    **Base URL:** `https://api.buckle.dev/v1` (Buckle Cloud) or
    `http://localhost:10254/v1` (self-hosted).


    ## Authentication


    Every endpoint takes an `Authorization: Bearer <token>` header unless its
    description says otherwise.


    - **Workspace API key** (`oc_…`) — acts inside one workspace. Read it from
    the dashboard or `GET /user/api-key`.

    - **Organization API key** (`oc_org_…`) — acts for the whole organization.
    Workspace-scoped endpoints additionally need an `X-Workspace-Id` header
    naming the workspace; without it they answer `401`.

    - **Dashboard session** — the browser's own session (Cloud: a bearer JWT;
    self-hosted: the session cookie).


    `X-Workspace-Id` replaced `X-Project-Id`. The old header, the `?_project`
    query bridge, and the `/v1/projects` path alias still work for a deprecation
    window and answer with a `Deprecation: true` header; migrate to the new
    names.


    ## Editions


    Each endpoint states where it is available. Unless marked otherwise an
    endpoint exists on **Buckle Cloud**, the **Community** self-hosted edition,
    and the **Enterprise** self-hosted edition. Endpoints tagged **Enterprise**
    answer `403` with `error.type: "enterprise_license_required"` on a
    self-hosted deployment that has not set `ENTERPRISE_ENABLED=true`; on Cloud
    they are always present, though some features are additionally gated by the
    organization's plan. Endpoints tagged **Cloud** do not exist on self-hosted
    deployments at all.


    ## Roles


    Organization-level endpoints (`/org/…`) require the **admin** or **owner**
    role wherever roles are enforced (Cloud and Enterprise). The Community
    edition runs a flat team: every active member passes the role check.
servers:
  - url: https://api.buckle.dev/v1
    description: Buckle Cloud
  - url: http://localhost:10254/v1
    description: Self-hosted
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: >-
      Workspaces partition an organization's agents, secrets, and connections.
      Every workspace-scoped endpoint resolves its workspace from the API key
      (or `X-Workspace-Id` with an organization key).
  - name: Agents
    description: >-
      Manage agents, their gateway access tokens, and hosted-agent
      configuration.
  - name: Grants
    description: >-
      Which credentials each agent may use — attach app connections (with
      optional per-tool allow/approval lists and resource scoping) and secrets.
      Writes take effect immediately.
  - name: Secrets
    description: >-
      Credentials the gateway injects into outbound requests that match a host
      pattern.
  - name: Apps
    description: >-
      The app catalog, OAuth and direct-credential connects, your own OAuth
      client configuration, permission catalogs, and blocklists.
  - name: Connections
    description: Connected app accounts as a top-level resource.
  - name: Effective policy
    description: >-
      Read-only reflections of what the enforced policy means for an agent, a
      connection, or an app — workspace grants composed with organization rules.
  - name: Conversations
    description: >-
      Talk to a hosted agent. A conversation owns its turns, transcript, and
      attachments.
  - name: Schedules
    description: Cron-style schedules on a hosted agent.
  - name: Memories
    description: A hosted agent's memory files and their revision history.
  - name: Skills
    description: >-
      Skills reachable from a workspace — the organization's, the workspace's
      own, and per-agent ones.
  - name: Channels
    description: >-
      Where a hosted agent is reachable (Slack), who may reach it, who it may
      message, and which other agents it may talk to.
  - name: Approvals
    description: Long-poll for the gateway's manual-approval requests and submit decisions.
  - name: User
    description: Your profile, API keys, SSH keys, and account deletion.
  - name: Instance
    description: Unauthenticated deployment facts and bootstrap endpoints.
  - name: Utility
    description: Counts, vaults, and agent bootstrap helpers.
  - name: Organization
    description: The current organization and its invitations. Free on every edition.
  - name: Organization secrets
    description: Secrets shared into every workspace of the organization.
  - name: Organization policy
    description: >-
      The organization's first-match rule set — blocks, allows, rate limits,
      approvals, and app permissions that bind every workspace.
  - name: Organization connections
    description: App connections shared into every workspace of the organization.
  - name: Organization apps
    description: >-
      Connect apps and configure your own OAuth clients at the organization
      level.
  - name: Organization skills
    description: Skills every workspace in the organization receives.
  - name: Organization channels
    description: The organization's Slack integration and identity links.
  - name: Organization approvals
    description: Long-poll for manual-approval requests across every workspace.
  - name: Members
    description: The organization directory — list, provision, suspend, and remove members.
  - name: Groups
    description: Directory groups and group-to-role mappings.
  - name: Workspace access
    description: Share a workspace with people and groups.
  - name: Domains
    description: Verified email domains, the anchor for SSO and home-realm discovery.
  - name: SSO
    description: SAML and OIDC sign-in connections and organization-wide enforcement.
  - name: SCIM tokens
    description: Bearer tokens for the organization's SCIM endpoint.
  - name: App availability
    description: Restrict which apps each workspace may connect.
  - name: Provisioning
    description: >-
      Pre-create members with a ready workspace and API key, then let them claim
      the account.
  - name: Resource browsing
    description: Browse a connected account's folders to pick resource scopes for a grant.
  - name: SCIM
    description: >-
      The SCIM 2.0 provisioning endpoint for identity providers (Okta, Entra ID,
      and others).
paths:
  /agents/{agentId}/grants/connections/{connectionId}:
    put:
      tags:
        - Grants
      summary: Attach a connection to an agent
      description: >
        Attach an app connection to an agent, or change what the agent may do
        with it. Takes effect immediately — there is no draft/publish step.


        Send `{"access": "full"}` for every tool the app supports, or
        `{"access": "custom", "allow": [...], "ask": [...]}` to name tools:
        `allow` runs freely, `ask` pauses each call for human approval, and
        everything unnamed is blocked. Add `resources` to scope the credential
        to specific repositories or folders (Enterprise).
      operationId: setAgentConnectionGrant
      parameters:
        - $ref: '#/components/parameters/agentId'
        - $ref: '#/components/parameters/connectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionGrantInput'
      responses:
        '200':
          description: The agent's updated grant set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGrants'
        '403':
          description: >-
            Resource scoping without the Enterprise entitlement (self-hosted) or
            a plan that includes it (Cloud)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent or connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >
            Invalid grant. The two validation laws: a custom grant must name at
            least one tool across `allow` and `ask` (`Custom access needs at
            least one allowed or approval tool. To block everything, detach
            instead.`), and a tool can't appear in both lists (`A tool can't be
            both always-allowed and require approval.`). Unknown tool ids are
            also rejected — valid ids come from `GET
            /apps/{provider}/permission-definition`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    agentId:
      name: agentId
      in: path
      required: true
      schema:
        type: string
    connectionId:
      name: connectionId
      in: path
      required: true
      schema:
        type: string
  schemas:
    ConnectionGrantInput:
      description: >
        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).
      oneOf:
        - type: object
          title: Full access
          required:
            - access
          properties:
            access:
              type: string
              enum:
                - full
            resources:
              allOf:
                - $ref: '#/components/schemas/SessionPolicy'
              nullable: true
          additionalProperties: false
        - type: object
          title: Custom access
          required:
            - access
            - allow
            - ask
          properties:
            access:
              type: string
              enum:
                - custom
            allow:
              type: array
              maxItems: 200
              items:
                type: string
              description: Tool ids the agent may call freely.
            ask:
              type: array
              maxItems: 200
              items:
                type: string
              description: Tool ids that require human approval on every call.
            resources:
              allOf:
                - $ref: '#/components/schemas/SessionPolicy'
              nullable: true
          additionalProperties: false
    AgentGrants:
      type: object
      description: >-
        An agent's full grant set — returned by grant reads and by every grant
        write.
      properties:
        agentId:
          type: string
        mode:
          type: string
          enum:
            - all
            - grants
          description: >-
            Always `grants` on current servers. The `all` value is wire
            compatibility with older self-hosted releases; never branch behavior
            on it.
        connections:
          type: array
          items:
            $ref: '#/components/schemas/AgentGrantConnection'
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/AgentGrantSecret'
    Error:
      description: >
        Error responses take one of two shapes depending on the failing layer:
        route-level validation returns the flat shape (`{ "error": "..." }`),
        while authentication failures and service errors return the envelope (`{
        "error": { "message": "...", "type": "..." } }`).
      oneOf:
        - $ref: '#/components/schemas/ErrorFlat'
        - $ref: '#/components/schemas/ErrorEnvelope'
    SessionPolicy:
      description: >
        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.
      oneOf:
        - type: object
          title: GitHub repositories
          required:
            - repositories
          properties:
            repositories:
              type: array
              minItems: 1
              maxItems: 1000
              items:
                type: string
          additionalProperties: false
        - type: object
          title: Dropbox folders
          required:
            - folders
          properties:
            folders:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: string
          additionalProperties: false
        - type: object
          title: Google Drive folders
          required:
            - driveFolders
          properties:
            driveFolders:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: string
          additionalProperties: false
    AgentGrantConnection:
      type: object
      description: One app connection granted to an agent.
      properties:
        connectionId:
          type: string
        provider:
          type: string
          description: App provider, for example `gmail`.
        label:
          type: string
          nullable: true
          description: The connection's label — distinguishes multiple accounts of one app.
        scope:
          type: string
          enum:
            - workspace
            - organization
          description: >-
            Where the connection lives. Organization connections are shared into
            every workspace.
        access:
          type: string
          enum:
            - full
            - custom
          description: >-
            `full` = every tool the app supports; `custom` = only the
            `allow`/`ask` lists below.
        allow:
          type: array
          items:
            type: string
          description: Tool ids the agent may call freely. Empty when `access` is `full`.
        ask:
          type: array
          items:
            type: string
          description: >-
            Tool ids that pause for human approval on every call. Empty when
            `access` is `full`.
        resources:
          allOf:
            - $ref: '#/components/schemas/SessionPolicy'
          nullable: true
          description: The grant's resource scoping, or null for unrestricted.
    AgentGrantSecret:
      type: object
      description: >-
        One secret granted to an agent. Secrets are all-or-nothing — no per-tool
        lists.
      properties:
        secretId:
          type: string
        name:
          type: string
        type:
          type: string
          description: '`generic` is a plain secret; `anthropic`/`openai` are LLM keys.'
        scope:
          type: string
          enum:
            - workspace
            - organization
    ErrorFlat:
      type: object
      description: Flat error shape used by route-level validation.
      required:
        - error
      properties:
        error:
          type: string
    ErrorEnvelope:
      type: object
      description: >-
        Envelope error shape used for authentication failures and service
        errors.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              description: >-
                Error category: `authentication_error`, `invalid_request_error`,
                `not_found_error`, `validation_error`, `rate_limit_error`,
                `enterprise_license_required`, or `api_error`.
            code:
              type: string
              description: >-
                Present on some `401`s (for example when the organization
                requires SSO).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A workspace API key (`oc_…`) or organization API key (`oc_org_…`).
        Workspace-scoped endpoints called with an organization key also need
        `X-Workspace-Id`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.