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

# Begin authorizing a third-party account connection

> Begins authorizing a third-party account connection and returns the provider URL to send the operator to, together with a single-use, short-lived state nonce. A caller may also continue one of the opaque provider options returned by managedAgentsCompleteIntegrationInstall. Nothing is connected until completion succeeds. Do not automatically retry an ambiguous transport failure; begin a new install and use its returned state.



## OpenAPI

````yaml /recursion/openapi.yaml post /managed-agents/v1/integrations/{provider}/install
openapi: 3.1.0
info:
  title: Managed Agents API
  version: 0.14.0
  description: >-
    The Recursion Managed Agents REST API. Authenticate with a Recursion API key
    as a bearer token. An organization-scoped key acts in its own organization
    and needs nothing else; a tenant-scoped key must also send
    `x-organization-id` with an organization id or `default`. Field names follow
    each operation's published schema.
servers:
  - url: https://api.recursion.labelbox.com
security:
  - bearerAuth: []
paths:
  /managed-agents/v1/integrations/{provider}/install:
    post:
      tags:
        - Integrations
      summary: Begin authorizing a third-party account connection
      description: >-
        Begins authorizing a third-party account connection and returns the
        provider URL to send the operator to, together with a single-use,
        short-lived state nonce. A caller may also continue one of the opaque
        provider options returned by managedAgentsCompleteIntegrationInstall.
        Nothing is connected until completion succeeds. Do not automatically
        retry an ambiguous transport failure; begin a new install and use its
        returned state.
      operationId: managedAgentsStartIntegrationInstall
      parameters:
        - description: >-
            Integration provider id returned by
            managedAgentsListIntegrationProviders.
          in: path
          name: provider
          required: true
          schema:
            description: >-
              Integration provider id returned by
              managedAgentsListIntegrationProviders.
            minLength: 1
            type: string
        - $ref: '#/components/parameters/RecursionTenantId'
        - $ref: '#/components/parameters/RecursionOrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartIntegrationInstallRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallStart'
          description: >-
            Where to send a user to authorize an integration, plus the one-time
            state nonce that ties the provider's callback back to this attempt.
            Returned when an authorization flow is started.
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson'
                  - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest'
                discriminator:
                  propertyName: code
                  mapping:
                    invalid_json: '#/components/schemas/ManagedAgentsApiErrorInvalidJson'
                    invalid_request: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest'
                x-recursion-error-codes:
                  - invalid_json
                  - invalid_request
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized'
                x-recursion-error-codes:
                  - unauthorized
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden'
                x-recursion-error-codes:
                  - forbidden
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound'
                x-recursion-error-codes:
                  - not_found
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '413':
          description: Payload Too Large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge'
                x-recursion-error-codes:
                  - payload_too_large
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '415':
          description: Unsupported Media Type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType'
                x-recursion-error-codes:
                  - unsupported_media_type
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '429':
          headers:
            Retry-After:
              description: >-
                When present, delay in seconds or an HTTP-date after which the
                caller may retry; absence supplies no retry advice.
              schema:
                type: string
              style: simple
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
          description: Too Many Requests.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ManagedAgentsApiErrorMergeRateLimited'
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded
                discriminator:
                  propertyName: code
                  mapping:
                    merge_rate_limited: '#/components/schemas/ManagedAgentsApiErrorMergeRateLimited'
                    rate_limit_exceeded: >-
                      #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded
                x-recursion-error-codes:
                  - merge_rate_limited
                  - rate_limit_exceeded
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError'
                x-recursion-error-codes:
                  - internal_error
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '502':
          description: A dependent service returned an invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure'
                x-recursion-error-codes:
                  - bad_gateway
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '503':
          description: Service Unavailable.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorBuiltInIntegrationsUnconfigured
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorCredentialEncryptionUnconfigured
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable
                  - $ref: '#/components/schemas/ManagedAgentsApiErrorMergeUnavailable'
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorServiceUnavailable
                discriminator:
                  propertyName: code
                  mapping:
                    built_in_integrations_unconfigured: >-
                      #/components/schemas/ManagedAgentsApiErrorBuiltInIntegrationsUnconfigured
                    credential_encryption_unconfigured: >-
                      #/components/schemas/ManagedAgentsApiErrorCredentialEncryptionUnconfigured
                    managed_agents_unavailable: >-
                      #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable
                    merge_unavailable: '#/components/schemas/ManagedAgentsApiErrorMergeUnavailable'
                    service_unavailable: >-
                      #/components/schemas/ManagedAgentsApiErrorServiceUnavailable
                x-recursion-error-codes:
                  - built_in_integrations_unconfigured
                  - credential_encryption_unconfigured
                  - managed_agents_unavailable
                  - merge_unavailable
                  - service_unavailable
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '504':
          headers:
            Retry-After:
              description: When to retry, as delay seconds or an HTTP date.
              schema:
                type: string
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
          description: A dependent service timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout'
                x-recursion-error-codes:
                  - gateway_timeout
components:
  parameters:
    RecursionTenantId:
      name: x-tenant-id
      in: header
      required: false
      description: >-
        Optional tenant consistency check. When present, it must name the tenant
        bound to the API key, including when x-organization-id is `default`.
      schema:
        type: string
        minLength: 1
    RecursionOrganizationId:
      name: x-organization-id
      in: header
      required: false
      description: >-
        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`.
      schema:
        type: string
        minLength: 1
  schemas:
    StartIntegrationInstallRequest:
      description: >-
        Optional input for starting or continuing an integration authorization.
        It may select a provider-defined continuation or an existing connection
        to re-authorize; organization identity always comes from the
        authenticated caller.
      properties:
        connection_id:
          description: >-
            Existing connection to re-authorize in place, keeping its id and
            therefore the vault grants that reference it. Omit to create a new
            connection. The connection must belong to the caller's organization
            and use this provider; it is recorded server-side against the
            returned state, never read back from the provider callback.
          format: uuid
          type: string
        option:
          description: >-
            Short opaque provider option: either a continuation value returned
            by a prior completion, or -- for a provider whose catalog entry
            reports preset_fixed_at_authorization -- the permission preset to
            authorize (see ProviderInfo.permissions). Omit for a provider
            needing neither.
          maxLength: 30
          type: string
      type: object
      additionalProperties: false
    InstallStart:
      description: >-
        Where to send a user to authorize an integration, plus the one-time
        state nonce that ties the provider's callback back to this attempt.
        Returned when an authorization flow is started.
      properties:
        state:
          description: >-
            Single-use CSRF nonce identifying this install attempt, not a
            lifecycle status. The provider must echo it in the callback;
            completion consumes the server-held record that binds it to the
            provider, organization, and user.
          type: string
        url:
          description: >-
            Absolute provider-hosted authorization page to redirect the user to.
            Carries the state nonce as a query parameter; send the user here
            rather than fetching it server-side.
          type: string
      required:
        - url
        - state
      type: object
      additionalProperties: false
    ManagedAgentsApiErrorInvalidJson:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - invalid_json
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorInvalidRequest:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - invalid_request
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorUnauthorized:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - unauthorized
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorForbidden:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - forbidden
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorNotFound:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - not_found
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorPayloadTooLarge:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - payload_too_large
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorUnsupportedMediaType:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - unsupported_media_type
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorMergeRateLimited:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - merge_rate_limited
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorRateLimitExceeded:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - rate_limit_exceeded
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorInternalError:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - internal_error
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorDependencyFailure:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - bad_gateway
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorBuiltInIntegrationsUnconfigured:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - built_in_integrations_unconfigured
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorCredentialEncryptionUnconfigured:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - credential_encryption_unconfigured
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorManagedAgentsUnavailable:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - managed_agents_unavailable
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorMergeUnavailable:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - merge_unavailable
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorServiceUnavailable:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - service_unavailable
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorDependencyTimeout:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - gateway_timeout
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorDetails:
      type: object
      properties:
        field:
          description: >-
            Request field or header responsible for the error, when one can be
            identified.
          type: string
        issues:
          description: >-
            Boundary-validation failures as path-prefixed human-readable
            messages.
          type: array
          items:
            type: string
        requestId:
          description: Request correlation identifier for support and log lookup.
          type: string
        retryable:
          description: >-
            Server advice about failure transience. `true` means transient,
            `false` means non-transient, and absence gives no advice. Automatic
            replay is allowed only when this field is not `false` and the
            operation-specific retry and idempotency contract permits replay.
          type: boolean
      additionalProperties:
        $ref: '#/components/schemas/PlatformSafeJsonValue'
      description: >-
        Optional structured error details. Reserved transport fields are typed;
        code-specific fields remain forward compatible.
    PlatformSafeJsonValue:
      description: >-
        A JSON value whose integer members stay within the exact ECMAScript
        safe-integer range at every nesting level.
      oneOf:
        - type: 'null'
        - type: boolean
        - type: string
        - type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        - type: number
          not:
            type: integer
        - type: array
          items:
            $ref: '#/components/schemas/PlatformSafeJsonValue'
        - additionalProperties:
            $ref: '#/components/schemas/PlatformSafeJsonValue'
          type: object
  headers:
    RecursionOrganizationId:
      description: Organization id resolved for this request.
      schema:
        type: string
        minLength: 1
    RecursionTenantId:
      description: Tenant id resolved for this request.
      schema:
        type: string
        minLength: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Recursion API key, created in the console under API keys.

````