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

# Begin a Connection setup session

> Begin setup for one exact qualified IntegrationOffering and Principal. Checkfu resolves an opaque placement choice, applies the package's reviewed scope and egress defaults unless the caller narrows them, reserves immutable Connection and revision identities before adapter I/O, and returns a durable ConnectionSession plus a short-lived trusted-origin URL only when a person must finish OAuth, credential entry, or Bridge pairing. Keep that begin receipt in the reviewed human-completion surface; model-safe follow-up uses getConnectionSession or observeConnectionSession. Requires an Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: connection-lifecycle. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.



## OpenAPI

````yaml /openapi.json post /v1/principals/{id}/connection-sessions
openapi: 3.1.0
info:
  title: Checkfu API
  version: '2026-08-27'
  description: >-
    Authentication is declared per operation: API-key, runtime, or connector
    bearer; Automation signature; or credential-free pairing redemption. Every
    general Checkfu REST request requires the dated `Checkfu-Version` header
    (one of: 2026-08-27); the three MCP JSON-RPC transports use
    `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth
    callback carries neither Checkfu header. API keys resolve one Workspace
    without a request selector; authenticated responses identify it with
    `Checkfu-Workspace-Id`.
servers:
  - url: https://api.checkfu.com
security:
  - bearerAuth: []
tags:
  - name: organizations
  - name: sourceRepositories
  - name: tenants
  - name: workspaces
  - name: principals
  - name: principalGroups
  - name: principalAccessCredentials
  - name: apiKeys
  - name: agents
  - name: harnesses
  - name: harnessRuntime
  - name: sandboxProfiles
  - name: computerProfiles
  - name: permissionAssignments
  - name: actionPolicies
  - name: files
  - name: memoryStores
  - name: dreams
  - name: modelCredentials
  - name: modelRoutingProfiles
  - name: blueprintInstallations
  - name: toolSources
  - name: skills
  - name: skillSources
  - name: agentSources
  - name: skillProposals
  - name: instructionProposals
  - name: catalog
  - name: concepts
  - name: support
  - name: connections
  - name: connectionVaults
  - name: connectionAssignments
  - name: connectedRuntimes
  - name: projects
  - name: collaboration
  - name: automationGraphs
  - name: automations
  - name: actionApprovals
  - name: standingApprovals
  - name: usage
  - name: models
  - name: outcomes
  - name: budgets
  - name: billing
  - name: sessions
  - name: audit
  - name: sessionExports
  - name: runs
  - name: runnerPools
  - name: transcripts
  - name: sessionWatches
  - name: webhookEndpoints
  - name: integrationGateway
  - name: agentDeployments
  - name: workEnvironments
  - name: computers
  - name: computerScreens
  - name: computerBrowserObservations
  - name: computerBrowserActions
  - name: environments
  - name: vaults
  - name: apiMcp
  - name: a2a
paths:
  /v1/principals/{id}/connection-sessions:
    post:
      tags:
        - integrationGateway
      summary: Begin a Connection setup session
      description: >-
        Begin setup for one exact qualified IntegrationOffering and Principal.
        Checkfu resolves an opaque placement choice, applies the package's
        reviewed scope and egress defaults unless the caller narrows them,
        reserves immutable Connection and revision identities before adapter
        I/O, and returns a durable ConnectionSession plus a short-lived
        trusted-origin URL only when a person must finish OAuth, credential
        entry, or Bridge pairing. Keep that begin receipt in the reviewed
        human-completion surface; model-safe follow-up uses getConnectionSession
        or observeConnectionSession. Requires an Idempotency-Key.


        Checkfu support posture: alpha; hosted. Required evidence journey:
        connection-lifecycle. Deployment-specific readiness and the latest
        proven release are available from GET /v1/support/capabilities.
      operationId: integrationGateway.beginConnectionSession
      parameters:
        - name: id
          in: path
          schema:
            $ref: '#/components/schemas/PrincipalId'
          required: true
        - name: checkfu-version
          in: header
          schema:
            type: string
            enum:
              - '2026-08-27'
          required: true
        - name: idempotency-key
          in: header
          schema:
            type: string
            allOf:
              - maxLength: 255
              - minLength: 1
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeginConnectCenterSession'
        required: true
      responses:
        '201':
          description: >-
            one open-URL action with the session deadline exactly while human
            completion is pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedConnectionSession'
          headers:
            checkfu-workspace-id:
              description: The Workspace resolved from the authenticated bearer credential.
              required: true
              schema:
                $ref: '#/components/schemas/WorkspaceId'
        '400':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - validation.malformed
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#validation-malformed
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    required:
                      - type
                      - message
                      - more
                    additionalProperties: false
                additionalProperties: false
        '401':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                      - more
                    properties:
                      type:
                        type: string
                        enum:
                          - auth.invalid_key
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#auth-invalid-key
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    additionalProperties: false
                additionalProperties: false
        '403':
          description: >-
            The organization, tenant, or workspace backing this key is
            administratively disabled. | Deployment governance or retention
            policy denied the request.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    required:
                      - error
                    properties:
                      error:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - auth.disabled_tenancy
                          message:
                            type: string
                          more:
                            type: string
                            enum:
                              - >-
                                https://docs.checkfu.com/reference/errors#auth-disabled-tenancy
                            description: >-
                              Stable public documentation and remedy for this
                              error type.
                        required:
                          - type
                          - message
                          - more
                        additionalProperties: false
                    additionalProperties: false
                  - $ref: '#/components/schemas/PolicyDeniedError'
        '404':
          description: >-
            The requested resource does not exist in the resolved deployment
            boundary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationNotFoundError'
        '409':
          description: >-
            The request conflicts with the resource's current state. | An
            idempotent mutation conflicts with a completed or in-progress
            request for the same key.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationConflictError'
                  - $ref: '#/components/schemas/IdempotencyConflictError'
        '429':
          description: Typed Checkfu wire error
          headers:
            retry-after:
              description: >-
                Delay in seconds for rate limits or deployment quotas with a
                known release or UTC reset boundary
              required: false
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                      - more
                    properties:
                      type:
                        type: string
                        enum:
                          - budget.exceeded
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#budget-exceeded
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    additionalProperties: false
                additionalProperties: false
        '500':
          description: >-
            An unexpected internal failure occurred; the message contains an
            opaque incident reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    PrincipalId:
      type: string
      allOf:
        - pattern: ^prin_[0-9a-f]{32}$
    BeginConnectCenterSession:
      type: object
      properties:
        offering_id:
          $ref: '#/components/schemas/IntegrationOfferingId'
        label:
          type: string
          allOf:
            - minLength: 1
            - maxLength: 8192
        placement_id:
          type: string
          allOf:
            - pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
        return_url:
          $ref: '#/components/schemas/PublicHttpsRedirectUrl'
        scopes:
          $ref: '#/components/schemas/Arrays_38'
        egress_rules:
          type: array
          items:
            $ref: '#/components/schemas/EgressRule'
          allOf:
            - minItems: 1
            - maxItems: 32
      required:
        - offering_id
        - label
        - return_url
      additionalProperties: false
    IssuedConnectionSession:
      type: object
      properties:
        session:
          $ref: '#/components/schemas/ConnectionSession'
        next_action:
          $ref: '#/components/schemas/Union_387'
      required:
        - session
        - next_action
      additionalProperties: false
    WorkspaceId:
      type: string
      allOf:
        - pattern: ^wrkspc_[0-9a-f]{32}$
    PolicyDeniedError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - policy.denied
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#policy-denied
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: Deployment governance or retention policy denied the request.
    ValidationNotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.not_found
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-not-found
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        The requested resource does not exist in the resolved deployment
        boundary.
    ValidationConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.conflict
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-conflict
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: The request conflicts with the resource's current state.
    IdempotencyConflictError:
      anyOf:
        - $ref: '#/components/schemas/ValidationIdempotencyConflictError'
        - $ref: '#/components/schemas/ValidationIdempotencyInProgressError'
      description: >-
        An idempotent mutation conflicts with a completed or in-progress request
        for the same key.
    RuntimeInternalError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - runtime.internal
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#runtime-internal
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        An unexpected internal failure occurred; the message contains an opaque
        incident reference.
    IntegrationOfferingId:
      type: string
      allOf:
        - pattern: ^ioff_[0-9a-f]{32}$
    PublicHttpsRedirectUrl:
      type: string
      allOf:
        - pattern: ^https:\/\/[^\s#]+$
        - maxLength: 2048
    Arrays_38:
      type: array
      items:
        $ref: '#/components/schemas/ConnectionScope'
      allOf:
        - maxItems: 256
        - minItems: 1
    EgressRule:
      type: object
      properties:
        scheme:
          type: string
          enum:
            - https
        host:
          $ref: '#/components/schemas/PublicHostname'
        port:
          type: integer
          allOf:
            - minimum: 1
              maximum: 65535
        path_prefix:
          $ref: '#/components/schemas/HttpPath'
        methods:
          type: array
          items:
            $ref: '#/components/schemas/HttpMethod'
          allOf:
            - minItems: 1
            - maxItems: 7
        allowed_headers:
          $ref: '#/components/schemas/AllowedEgressHeaders'
      required:
        - scheme
        - host
        - port
        - path_prefix
        - methods
      additionalProperties: false
      description: One reviewed HTTPS destination and bounded method/header authority.
    ConnectionSession:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ConnectionSessionId'
        workspace_id:
          $ref: '#/components/schemas/WorkspaceId'
        owner_principal_id:
          $ref: '#/components/schemas/PrincipalId'
        connection_id:
          $ref: '#/components/schemas/ConnectionId'
        connection_revision_id:
          $ref: '#/components/schemas/ConnectionRevisionId'
        operation:
          type: string
          enum:
            - connect
            - reconnect
            - revoke
        flow:
          anyOf:
            - $ref: '#/components/schemas/Union_386'
            - type: 'null'
        status:
          type: string
          enum:
            - pending_runtime
            - pending_human
            - connected
            - revoked
            - failed
            - expired
            - canceled
        failure:
          anyOf:
            - type: string
              enum:
                - client_rejected
                - connection_changed
                - credential_rejected
                - offering_unavailable
                - provider_unavailable
            - type: 'null'
        cleanup_pending:
          type: boolean
        expires_at:
          $ref: '#/components/schemas/IntegrationGatewayInstant'
        version:
          type: integer
          allOf:
            - exclusiveMinimum: 0
        created_at:
          $ref: '#/components/schemas/IntegrationGatewayInstant'
        updated_at:
          $ref: '#/components/schemas/IntegrationGatewayInstant'
      required:
        - id
        - workspace_id
        - owner_principal_id
        - connection_id
        - connection_revision_id
        - operation
        - flow
        - status
        - failure
        - cleanup_pending
        - expires_at
        - version
        - created_at
        - updated_at
      additionalProperties: false
    Union_387:
      anyOf:
        - $ref: '#/components/schemas/ConnectionSessionAction'
        - type: 'null'
    ValidationIdempotencyConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.idempotency_conflict
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-conflict
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: The Idempotency-Key is already bound to a different request.
    ValidationIdempotencyInProgressError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.idempotency_in_progress
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        An identical idempotent request is still in progress and may be retried
        later.
    ConnectionScope:
      type: string
      allOf:
        - minLength: 1
        - maxLength: 512
        - pattern: ^[^\s,]+$
    PublicHostname:
      type: string
      allOf:
        - minLength: 1
        - maxLength: 253
        - pattern: ^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$
    HttpPath:
      type: string
      allOf:
        - minLength: 1
        - maxLength: 8192
    HttpMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
        - HEAD
        - OPTIONS
    AllowedEgressHeaders:
      type: array
      items:
        type: string
        allOf:
          - minLength: 1
          - maxLength: 128
          - pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$
      allOf:
        - maxItems: 128
    ConnectionSessionId:
      type: string
      allOf:
        - pattern: ^cns_[0-9a-f]{32}$
    ConnectionId:
      type: string
      allOf:
        - pattern: ^conn_[0-9a-f]{32}$
    ConnectionRevisionId:
      type: string
      allOf:
        - pattern: ^crev_[0-9a-f]{32}$
    Union_386:
      anyOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - oauth
          required:
            - kind
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - credential_entry
            credential_kind:
              type: string
              enum:
                - api_key
                - basic
                - service_account
          required:
            - kind
            - credential_kind
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - none
          required:
            - kind
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - bridge_pairing
          required:
            - kind
          additionalProperties: false
    IntegrationGatewayInstant:
      type: string
      allOf:
        - maxLength: 24
        - pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
          description: >-
            A canonical UTC ISO-8601 integration-gateway instant with
            millisecond precision.
    ConnectionSessionAction:
      type: object
      properties:
        kind:
          type: string
          enum:
            - open_url
        completion:
          $ref: '#/components/schemas/ConnectionSessionCompletion'
        url:
          $ref: '#/components/schemas/PublicHttpsRedirectUrl'
        expires_at:
          $ref: '#/components/schemas/IntegrationGatewayInstant'
      required:
        - kind
        - completion
        - url
        - expires_at
      additionalProperties: false
    ConnectionSessionCompletion:
      type: string
      enum:
        - callback
        - poll
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````