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

# Start a Provider connection setup

> Starts a setup of one Provider connection that the person completes in the Parable app, and returns a link for them. The person signs in, enters the credentials and connects. No credential passes through this call or its result. The link works for 30 minutes and for this person only, and it makes at most one connection. To start again after a setup expired, send a new idempotencyKey.

## Access

This operation needs a Parable token. An MCP token cannot call it. See [Authentication](https://developers.askparable.com/getting-started/authentication.md) for the kinds of token.

Your roles must grant `tenant.connectors.create`.

## Errors

* `HTTP 403`: The person cannot add Provider connections in this Workspace. Ask someone who manages the Workspace's Providers to connect it.
* `HTTP 404`: No way of connecting to a Provider has this groupingId. Read the ways of connecting with list\_ways\_connecting\_provider and use one of their ids.
* `WA-CN-005`: The Provider is not released for Workspace enablement. Choose a released Provider.
* `WA-CN-013`: This idempotencyKey already started a setup for another way of connecting. Send a new idempotencyKey.


## OpenAPI

````yaml /api-reference/openapi.json post /api/connectors/setups
openapi: 3.0.3
info:
  description: >-
    Use the Workspace API to work with artifacts, connectors, Parables, and
    account resources.
  title: Workspace API
  version: v2026.11.20.3
servers: []
security: []
paths:
  /api/connectors/setups:
    post:
      tags:
        - Connectors
      summary: Start a Provider connection setup
      description: >-
        Starts a setup of one Provider connection that the person completes in
        the Parable app, and returns a link for them. The person signs in,
        enters the credentials and connects. No credential passes through this
        call or its result. The link works for 30 minutes and for this person
        only, and it makes at most one connection. To start again after a setup
        expired, send a new idempotencyKey.
      operationId: ConnectorsStartProviderConnectionSetupHandler
      parameters:
        - description: >-
            Workspace slug. Overrides subdomain-based workspace resolution when
            provided.
          in: header
          name: X-Tenant
          required: false
          schema:
            example: acme
            type: string
        - description: Optional request correlation ID echoed back in the response.
          in: header
          name: X-Request-ID
          required: false
          schema:
            example: 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartProviderConnectionSetupInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProviderConnectionSetup'
                  links:
                    $ref: '#/components/schemas/ResponseLinks'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                  - data
                  - meta
                type: object
          description: Successful response
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: >-
            The request is not valid. `detail` says why. A value that breaks a
            field rule gives the code `WA-VL-001` and an `errors` member that
            names each field. The request must name a Workspace.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: The token is missing, malformed, revoked, or expired.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: >-
            The token cannot make this request. For example, the roles of its
            owner do not allow the operation.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: >-
            The Workspace sent more than 20 requests a minute to this operation.
            Wait for the number of seconds in `Retry-After`, then try again.
          headers:
            Retry-After:
              description: The number of seconds to wait before you try again.
              schema:
                type: integer
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: The request failed on the server.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: The server cannot check the rate limit now. Try again shortly.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
      security:
        - bearerAuth: []
      x-codeSamples:
        - label: TypeScript SDK
          lang: typescript
          source: >-
            import { WebApiSDK } from "@parable-platform/web-api-sdk";

            import type { StartProviderConnectionSetupInput } from
            "@parable-platform/web-api-types";


            const sdk = new WebApiSDK({
              baseUrl: process.env.PARABLE_API_URL!,
              auth: { token: process.env.PARABLE_API_TOKEN! },
              requestInterceptor: (config) => ({
                ...config,
                headers: { ...config.headers, "X-Tenant": process.env.PARABLE_WORKSPACE! },
              }),
            });


            const input: StartProviderConnectionSetupInput = JSON.parse(`{
              "groupingId": "example",
              "idempotencyKey": "example"
            }`);

            const result = await sdk.connectors.startProviderConnectionSetup(
              input
            );
        - label: Python SDK
          lang: python
          source: |-
            import json
            import os

            from parable_types_web_api import StartProviderConnectionSetupInput
            from parable_web_api_sdk import ClientConfig, WebApiSDK

            sdk = WebApiSDK(
                ClientConfig(
                    base_url=os.environ["PARABLE_API_URL"],
                    auth_token=os.environ["PARABLE_API_TOKEN"],
                    default_headers={"X-Tenant": os.environ["PARABLE_WORKSPACE"]},
                )
            )

            input_data = StartProviderConnectionSetupInput.model_validate(
                json.loads("{\"groupingId\":\"example\",\"idempotencyKey\":\"example\"}"),
            )
            result = sdk.connectors.start_provider_connection_setup(input_data)
        - label: Rust SDK
          lang: rust
          source: >-
            use parable_web_api_sdk::{types, ClientConfig, RequestOptions,
            WebApiSdk};


            let sdk = WebApiSdk::new(ClientConfig::with_base_url(
                std::env::var("PARABLE_API_URL")?,
                Some(std::env::var("PARABLE_API_TOKEN")?),
                None,
            ))?;

            let options = RequestOptions::with_header("X-Tenant",
            std::env::var("PARABLE_WORKSPACE")?, None, None);


            let input: types::StartProviderConnectionSetupInput =
            serde_json::from_value(
                serde_json::json!({
              "groupingId": "example",
              "idempotencyKey": "example"
            }),

            )?;

            let result = sdk.connectors.start_provider_connection_setup(
                input,
                Some(&options)
            ).await?;
        - label: Go SDK
          lang: go
          source: "sdk, err := webapisdk.New(webapisdk.SDKConfig{\n\tBaseURL: os.Getenv(\"PARABLE_API_URL\"),\n\tAuth:    &webapisdk.AuthConfig{Token: os.Getenv(\"PARABLE_API_TOKEN\")},\n\tRequestInterceptor: func(ctx context.Context, req *http.Request) error {\n\t\treq.Header.Set(\"X-Tenant\", os.Getenv(\"PARABLE_WORKSPACE\"))\n\t\treturn nil\n\t},\n})\nif err != nil {\n\treturn err\n}\n\nvar input webapitypes.StartProviderConnectionSetupInput\nif err := json.Unmarshal([]byte(`{\"groupingId\":\"example\",\"idempotencyKey\":\"example\"}`), &input); err != nil {\n\treturn err\n}\nresult, err := sdk.ConnectorsNamespace.StartProviderConnectionSetup(ctx, input)"
components:
  schemas:
    StartProviderConnectionSetupInput:
      additionalProperties: false
      description: >-
        Start a setup of one Provider connection that the person completes in
        the

        browser.
      properties:
        groupingId:
          description: |-
            The way of connecting to the Provider: an id that
            list_ways_connecting_provider gives.
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        idempotencyKey:
          description: The key of this call. The same key answers the same setup.
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
      required:
        - groupingId
        - idempotencyKey
      type: object
    ProviderConnectionSetup:
      description: One setup of a Provider connection in the browser. It holds no secret.
      properties:
        completedAt:
          description: When the person connected, and the connection they made.
          format: date-time
          nullable: true
          type: string
        connectionStatus:
          description: |-
            The connection's own status, such as a credential check that failed.
            Null until the person connects.
          oneOf:
            - $ref: '#/components/schemas/TenantConnectorStatusEnum'
            - enum:
                - null
              nullable: true
              type: string
        connectionStatusMessage:
          nullable: true
          type: string
        expiresAt:
          description: When the link stops working, if the person did not connect.
          format: date-time
          type: string
        groupingId:
          description: The way of connecting to the Provider, and its name.
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        groupingPath:
          type: string
        providerName:
          type: string
        setupId:
          description: UUID v4 with automatic base62 encoding for client-facing APIs
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        state:
          $ref: '#/components/schemas/ProviderConnectionSetupStateEnum'
        tenantConnectorId:
          description: UUID v4 with automatic base62 encoding for client-facing APIs
          nullable: true
          pattern: >-
            ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          type: string
        url:
          description: >-
            The link for the person. It opens the Workspace app, where the
            person

            signs in and enters the Provider's credentials. Only that person can
            use

            it.
          format: uri
          maxLength: 2048
          pattern: >-
            ^https?://[\w\-\{\}]+(\.[\w\-\{\}]+)+([:/?#][\w\-\._~:/?#\[\]@!\$&'\(\)\*\+,;=\{\}%]*)?$
          type: string
        vendorSlug:
          description: >-
            The Provider and the way of connecting, as the app's address names
            them.
          type: string
        workspaceSlug:
          description: The Workspace that the setup is for.
          type: string
      required:
        - setupId
        - url
        - state
        - groupingId
        - providerName
        - vendorSlug
        - groupingPath
        - workspaceSlug
        - expiresAt
      type: object
    ResponseLinks:
      properties:
        first:
          nullable: true
          type: string
        last:
          nullable: true
          type: string
        next:
          nullable: true
          type: string
        prev:
          nullable: true
          type: string
      type: object
    ResponseMeta:
      properties:
        requestId:
          description: Unique identifier for the request
          type: string
        totalCount:
          description: Total count of items for paginated responses
          nullable: true
          type: integer
      required:
        - requestId
      type: object
    ProblemDetails:
      description: An error response in the Problem Details format (RFC 9457).
      properties:
        code:
          description: The stable error code, when the problem has one.
          example: WA-VL-001
          type: string
        detail:
          description: What went wrong with this request.
          type: string
        details:
          description: >-
            Structured facts about the refusal, such as the entity or the path
            it concerns. Only some refusals have it.
        errors:
          description: >-
            The fields or filters that failed validation. Only a validation or
            filter error has it.
        requestId:
          description: >-
            The ID of the request, when the problem has one. The `X-Request-ID`
            response header always has it.
          type: string
        status:
          description: The HTTP status code.
          example: 400
          type: integer
        title:
          description: A short summary, usually the text of the HTTP status.
          example: Bad Request
          type: string
        type:
          description: >-
            The problem type. It is `about:blank`: the status and `code`
            identify the problem.
          example: about:blank
          type: string
      required:
        - type
        - title
        - status
        - detail
      type: object
    TenantConnectorStatusEnum:
      description: Operational status of a workspace connector instance.
      enum:
        - disabled
        - sync_failed
        - manual_validation_required
        - validation_pending
        - initial_syncing
        - update_syncing
        - sync_queued
        - idle
        - sync_partial_success
        - transform_quality_degraded
        - schedule_paused
        - config_invalid
        - credential_error
        - internal_error
        - ingestion_stale
      type: string
    ProviderConnectionSetupStateEnum:
      description: Where a setup of a Provider connection in the browser is.
      enum:
        - WAITING_FOR_PERSON
        - CONNECTED
        - EXPIRED
      type: string
  headers:
    X-Request-ID:
      description: >-
        The ID of the request. It is the `X-Request-ID` value that you sent, or
        an ID that the server made. Give it when you report a problem.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      description: >-
        A personal access token, which starts with `pat_`. A Parable token can
        call each operation that the roles of its owner allow. An MCP token can
        call only the read operations that are open to agents. A SQL token does
        not work on this API.
      scheme: bearer
      type: http

````

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