> ## 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. # Connect a Provider > Adds a Provider connection to this Workspace and applies the settings it needs to start working. > [!NOTE] > > Send this request body encrypted with your Workspace's encryption key. Parable refuses a plain JSON body with `400`. See [Encrypted request bodies](/getting-started/encryption.md). ## Access This operation needs a Parable token. An MCP token cannot call it. See [Authentication](/getting-started/authentication.md) for the kinds of token. Your roles must grant `tenant.connectors.create`. ## Errors * `WA-TN-001`: No Workspace context was supplied. Call from a Workspace context. * `WA-CN-002`: The selected authentication strategy was not found for this Provider. Choose an available Provider authentication strategy. * `WA-CN-005`: The Provider is not released for Workspace enablement. Choose a released Provider or ask an administrator to promote it. ## OpenAPI ````yaml /api-reference/openapi.json post /api/connectors openapi: 3.0.3 info: description: >- Use the Workspace API to work with artifacts, connectors, Parables, and account resources. title: Workspace API version: v2026.10.22.1 servers: [] security: [] paths: /api/connectors: post: tags: - Connectors summary: Connect a Provider description: >- Adds a Provider connection to this Workspace and applies the settings it needs to start working. operationId: ConnectorsAddConnectorToTenantHandler 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/AddConnectorToTenantInput' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/AddConnectorToTenantPayload' 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 body must be an encrypted envelope that the Workspace's encryption key opens. A plain JSON body fails. 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' '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' security: - bearerAuth: [] x-codeSamples: - label: TypeScript SDK lang: typescript source: >- import { WebApiSDK } from "@parable-platform/web-api-sdk"; import type { AddConnectorToTenantInput } 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! }, }), }); sdk.setPublicEncryptionKey(await sdk.security.encryptionKey()); const input: AddConnectorToTenantInput = JSON.parse(`{ "connectorId": "550e8400-e29b-41d4-a716-446655440000", "groupingId": "550e8400-e29b-41d4-a716-446655440000", "authenticationStrategyId": "550e8400-e29b-41d4-a716-446655440000", "authenticationConfig": {}, "ingestionConfig": {} }`); const result = await sdk.connectors.addConnectorToTenant( input ); - label: Python SDK lang: python source: >- import json import os from parable_types_web_api import AddConnectorToTenantInput from parable_web_api_sdk import ClientConfig, PublicEncryptionKey, 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"]}, ) ) key = sdk.security.encryption_key() sdk.set_public_encryption_key( PublicEncryptionKey(public_key=key.public_key, algorithm=key.algorithm, key_id=key.key_id) ) input_data = AddConnectorToTenantInput.model_validate( json.loads("{\"connectorId\":\"550e8400-e29b-41d4-a716-446655440000\",\"groupingId\":\"550e8400-e29b-41d4-a716-446655440000\",\"authenticationStrategyId\":\"550e8400-e29b-41d4-a716-446655440000\",\"authenticationConfig\":{},\"ingestionConfig\":{}}"), ) result = sdk.connectors.add_connector_to_tenant(input_data) - label: Rust SDK lang: rust source: >- use parable_web_api_sdk::{types, ClientConfig, EncryptedRequestOptions, PublicEncryptionKey, 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 key = sdk.security.encryption_key(Some(&options)).await?; let encrypted = EncryptedRequestOptions { public_encryption_key: Some(PublicEncryptionKey { public_key: key.public_key, algorithm: key.algorithm.to_string(), key_id: key.key_id, }), request_options: Some(options.clone()), }; let input: types::AddConnectorToTenantInput = serde_json::from_value( serde_json::json!({ "connectorId": "550e8400-e29b-41d4-a716-446655440000", "groupingId": "550e8400-e29b-41d4-a716-446655440000", "authenticationStrategyId": "550e8400-e29b-41d4-a716-446655440000", "authenticationConfig": {}, "ingestionConfig": {} }), )?; let result = sdk.connectors.add_connector_to_tenant( input, Some(&encrypted) ).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}\nkey, err := sdk.SecurityNamespace.EncryptionKey(ctx)\nif err != nil {\n\treturn err\n}\nsdk.SetPublicEncryptionKey(&webapisdk.PublicEncryptionKey{\n\tPublicKey: string(key.PublicKey),\n\tAlgorithm: string(key.Algorithm),\n\tKeyID: key.KeyId,\n})\n\nvar input webapitypes.AddConnectorToTenantInput\nif err := json.Unmarshal([]byte(`{\"connectorId\":\"550e8400-e29b-41d4-a716-446655440000\",\"groupingId\":\"550e8400-e29b-41d4-a716-446655440000\",\"authenticationStrategyId\":\"550e8400-e29b-41d4-a716-446655440000\",\"authenticationConfig\":{},\"ingestionConfig\":{}}`), &input); err != nil {\n\treturn err\n}\nresult, err := sdk.ConnectorsNamespace.AddConnectorToTenant(ctx, input, nil)" components: schemas: AddConnectorToTenantInput: properties: authenticationConfig: description: A Parable Schema in JSON type: object authenticationStrategyId: 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 connectorId: 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 groupingId: 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 idempotencyKey: nullable: true type: string ingestionConfig: description: A Parable Schema in JSON type: object name: description: An objects name maxLength: 80 minLength: 2 nullable: true type: string required: - connectorId - groupingId - authenticationStrategyId - authenticationConfig - ingestionConfig type: object AddConnectorToTenantPayload: description: Payload returned when adding a connector to a workspace properties: authenticationConfig: description: A Parable Schema in JSON type: object authenticationStrategy: $ref: '#/components/schemas/ConnectorAuthStrategy' createdAt: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time type: string credentialMetadataId: description: the result of setting the connector config 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 id: description: The id of the newly created workspace connector instance 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 ingestionConfig: description: A Parable Schema in JSON type: object message: description: a message related to setting the connector config type: string name: description: An objects name maxLength: 80 minLength: 2 nullable: true type: string success: description: was setting the connector config successful type: boolean tenant: $ref: '#/components/schemas/Tenant' required: - id - tenant - authenticationStrategy - authenticationConfig - ingestionConfig - createdAt - success - credentialMetadataId - message 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 ConnectorAuthStrategy: description: |- Authentication strategy row for a connector. Each strategy is persisted as its own record to support stable identity. properties: addressingConfig: description: >- Per-strategy API addressing configuration. Overrides the connector-level addressingConfig when this strategy is active. Variables with source=user_input must resolve from configSchema, this strategy's ingestionConfigSchema, or the connector's ingestionConfigSchema. oneOf: - $ref: '#/components/schemas/AddressingConfig' - enum: - null nullable: true type: object apiKeyConfig: description: API key settings (when type = API_KEY_HEADER or API_KEY_QUERY) oneOf: - $ref: '#/components/schemas/ApiKeyAuthConfig' - enum: - null nullable: true type: object basicConfig: description: Basic auth settings (when type = BASIC) oneOf: - $ref: '#/components/schemas/BasicAuthConfig' - enum: - null nullable: true type: object bearerConfig: description: Bearer token settings (when type = BEARER) oneOf: - $ref: '#/components/schemas/BearerAuthConfig' - enum: - null nullable: true type: object configSchema: description: Strategy-specific customer config schema nullable: true type: object createdAt: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time type: string createdBy: description: UUID v4 string as base62 pattern: ^[0-9A-Za-z]{1,22}$ type: string credentialProbe: description: >- Declarative credential check for this strategy. When set, credential validation runs it instead of a dedicated or generic probe. oneOf: - $ref: '#/components/schemas/CredentialProbeWorkflow' - enum: - null nullable: true type: object defaultBaseUrl: description: >- Per-strategy base URL override. Takes precedence over the connector-level defaultBaseUrl when this strategy is active. format: uri maxLength: 2048 nullable: true pattern: >- ^https?://[\w\-\{\}]+(\.[\w\-\{\}]+)+([:/?#][\w\-\._~:/?#\[\]@!\$&'\(\)\*\+,;=\{\}%]*)?$ type: string defaultScopes: description: Default OAuth2 scopes for this auth strategy items: type: string nullable: true type: array delegatedUserField: description: Ingestion config field name for delegated user email (DWD) nullable: true type: string docs: description: >- Per-strategy setup documentation (Markdown). When set, the Parable app shows it in place of the vendor grouping's docs for the selected auth method. nullable: true pattern: ^[\s\S]*$ type: string extraHeaders: additionalProperties: type: string description: Additional headers to include in all authenticated requests nullable: true type: object hook: description: Optional hook reference executed for auth strategy behavior nullable: true type: string id: 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 ingestionConfigSchema: description: >- Per-strategy ingestion config schema. When set, overrides the connector-level ingestionConfigSchema for workspace connectors using this auth strategy. nullable: true type: object label: description: Display label for this strategy in setup flows maxLength: 80 minLength: 2 nullable: true type: string oauth2Config: description: >- OAuth2 settings (when type = OAUTH2_CLIENT_CREDENTIALS or OAUTH2_REFRESH) oneOf: - $ref: '#/components/schemas/OAuth2AuthConfig' - enum: - null nullable: true type: object preEncodedBasicConfig: description: >- Pre-encoded basic auth settings (when type = BASIC with pre-encoded token) oneOf: - $ref: '#/components/schemas/PreEncodedBasicAuthConfig' - enum: - null nullable: true type: object support: description: |- Whether customers may use this strategy. Unset means supported when the backends run its type for this connector. oneOf: - $ref: '#/components/schemas/AuthStrategySupportEnum' - enum: - null nullable: true type: string type: $ref: '#/components/schemas/AuthMethodEnum' description: Authentication method updatedAt: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time type: string updatedBy: description: UUID v4 string as base62 pattern: ^[0-9A-Za-z]{1,22}$ type: string required: - id - createdAt - createdBy - updatedAt - updatedBy - type type: object Tenant: properties: createdAt: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time type: string createdBy: description: UUID v4 string as base62 pattern: ^[0-9A-Za-z]{1,22}$ type: string id: 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 logo: description: Workspace logo for branding. nullable: true type: object name: description: An objects name maxLength: 80 minLength: 2 type: string slug: description: A URL friendly version of a string maxLength: 17 minLength: 1 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ type: string updatedAt: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time type: string updatedBy: description: UUID v4 string as base62 pattern: ^[0-9A-Za-z]{1,22}$ type: string required: - id - createdAt - createdBy - updatedAt - updatedBy - name - slug type: object AddressingConfig: description: >- API addressing configuration for a connector or auth strategy. Defines the URL template and how each template variable is resolved at runtime. properties: basePath: description: >- Base path appended to host (e.g. /ex/jira/{cloudId}). Must start with /. nullable: true type: string host: description: >- API hostname. May contain {var} placeholders resolved from typed variables. nullable: true type: string scheme: description: URL scheme. Defaults to https when omitted by runtime consumers. nullable: true type: string variables: description: Typed declarations for {var} placeholders in host and basePath. items: $ref: '#/components/schemas/AddressingVariable' nullable: true type: array type: object ApiKeyAuthConfig: description: Configuration for API key authentication. properties: credentialHeaders: additionalProperties: type: string description: >- More headers sent with the API key on every request, for API_KEY_HEADER. Maps header name to the credential field whose value it carries, e.g. {'DD-APPLICATION-KEY': 'applicationKey'} beside headerName 'DD-API-KEY'. nullable: true type: object headerName: description: Header name for API_KEY_HEADER (e.g., 'X-API-Key') nullable: true type: string queryParam: description: Query parameter name for API_KEY_QUERY nullable: true type: string type: object BasicAuthConfig: description: Configuration for HTTP basic authentication. properties: passwordField: description: Config field path for password (e.g., 'auth.apiToken') type: string passwordValue: description: >- Static password when the API expects a fixed value (e.g. BambooHR HTTP Basic uses x). Applied when decrypted credentials omit the password field. nullable: true type: string usernameField: description: Config field path for username (e.g., 'auth.email') type: string required: - usernameField - passwordField type: object BearerAuthConfig: description: Configuration for bearer token authentication. properties: headerName: description: 'Header name (default: ''Authorization'')' nullable: true type: string tokenField: description: 'Token Field (defaults to: ''token'')' nullable: true type: string tokenPrefix: description: >- Token prefix (default: 'Bearer'); an empty prefix sends the bare token nullable: true type: string type: object CredentialProbeWorkflow: description: >- The credential check an auth strategy declares instead of the generic probe,. Operations run in order: the first one whose outcome is not success decides the verdict, and the credential is valid when every operation succeeds. success maps to VALID; auth_rejected, permission_denied and config_invalid to INVALID with that reason; retry and upstream_failure keep the stored status; expected_empty, and a response no rule matches, leave the credential unvalidated. properties: maxRequests: description: >- Most HTTP requests the workflow may send, retries included. Defaults to 6. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer operations: description: The operations to run, in order. items: $ref: '#/components/schemas/ProviderOperation' type: array signedTokens: description: Tokens the check signs from the credential. At most 4. items: $ref: '#/components/schemas/ProviderSignedToken' nullable: true type: array timeoutSeconds: description: >- Wall-clock budget for the whole workflow. Defaults to 30. A workflow that runs out of time keeps the stored credential status. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer writebacks: description: >- Extracted values written to the connection's ingestion config when every operation succeeds. A value that fails its target field's type, or that matches a credential or secret value, is withheld. items: $ref: '#/components/schemas/CredentialProbeWriteback' nullable: true type: array required: - operations type: object OAuth2AuthConfig: description: Configuration for OAuth 2.0 authentication flows. properties: audienceParam: description: Audience parameter (for APIs that require it) nullable: true type: string authorizeUrl: description: Authorization URL (for authorization code flow) format: uri maxLength: 2048 nullable: true pattern: >- ^https?://[\w\-\{\}]+(\.[\w\-\{\}]+)+([:/?#][\w\-\._~:/?#\[\]@!\$&'\(\)\*\+,;=\{\}%]*)?$ type: string grantType: description: OAuth2 grant type (e.g. client_credentials, account_credentials) oneOf: - $ref: '#/components/schemas/OAuthGrantType' - enum: - null nullable: true type: string passwordField: description: Credential field name for password (basic_credentials auth method) nullable: true type: string platformManagedClient: description: >- Whether Parable owns the OAuth client and supplies its credentials at runtime. nullable: true type: boolean resourceHeaders: additionalProperties: type: string description: Maps resource request header names to credential field names. nullable: true type: object scopes: description: >- OAuth scopes for the token request (space-joined in the token POST body per RFC 6749) items: type: string nullable: true type: array tokenBodyEncoding: description: Token request body encoding (form by default). oneOf: - $ref: '#/components/schemas/BodyEncodingEnum' - enum: - null nullable: true type: string tokenEndpoint: description: Token endpoint URL format: uri maxLength: 2048 pattern: >- ^https?://[\w\-\{\}]+(\.[\w\-\{\}]+)+([:/?#][\w\-\._~:/?#\[\]@!\$&'\(\)\*\+,;=\{\}%]*)?$ type: string tokenEndpointAuthMethod: description: How credentials are sent to the token endpoint oneOf: - $ref: '#/components/schemas/TokenEndpointAuthMethod' - enum: - null nullable: true type: string tokenEndpointExtraParams: description: Maps token request param names to credential field names nullable: true tokenPrefix: description: 'Authorization header prefix (default: Bearer)' nullable: true type: string tokenReadinessDelaySeconds: description: >- Delay between token issuance and the first request that uses the token. format: int64 maximum: 10 minimum: 0 nullable: true type: integer tokenRefreshCodes: description: >- HTTP failure status codes on API responses that trigger an OAuth2 access-token refresh and a single retry of the same request (client-credentials flow). When this field is omitted, ingestion defaults to HTTP 401 as the only refresh trigger (equivalent to a list containing 401), so long paginated syncs can recover after token TTL (for example Microsoft Graph). Pass an explicit empty list to disable HTTP-triggered refresh; proactive refresh near local token expiry may still apply. items: description: HTTP response status code, 100 through 599 format: int64 maximum: 599 minimum: 400 type: integer nullable: true type: array tokenResponsePath: description: 'Dot-separated path to token in response JSON (default: access_token)' nullable: true type: string usernameField: description: Credential field name for username (basic_credentials auth method) nullable: true type: string required: - tokenEndpoint type: object PreEncodedBasicAuthConfig: description: |- Configuration for pre-encoded HTTP basic authentication. Uses an already-encoded Base64 token instead of username:password. properties: tokenField: description: Credential field name for the pre-encoded Base64 token type: string required: - tokenField type: object AuthStrategySupportEnum: description: >- Whether customers may use an auth strategy. A strategy is usable only when Parable can both validate its credentials and ingest with it. The catalog may record a strategy that the vendor offers and Parable cannot run yet. It does not offer that strategy to customers. enum: - supported - unsupported type: string AuthMethodEnum: description: Authentication method for API calls. enum: - bearer - basic - api_key_header - api_key_query - oauth2_client_credentials - oauth2_refresh - google_domain_wide_delegation - oauth2_jwt_bearer - oauth2_auth_code_pkce - session_exchange - session_exchange_jwt - session_exchange_password - custom - saml - mtls - ssh_key - kerberos - aws_sig_v4 - gcp_service_account - hmac - digest - ntlm - azure_ad - oauth2_device_code type: string AddressingVariable: description: A single template variable in an AddressingConfig. properties: name: description: Name of the {var} placeholder in host or basePath. type: string oauthResponsePath: description: |- Dot-separated path into the OAuth token response body. Required when source = oauth_response. nullable: true type: string required: description: Whether a missing value for this variable should halt the sync. nullable: true type: boolean source: description: 'Resolution source: user_input, oauth_response, or static.' type: string required: - name - source type: object ProviderOperation: description: One request and the rules that judge its response. properties: extracts: description: Values read from the response when the operation succeeds. items: $ref: '#/components/schemas/ProviderExtract' nullable: true type: array id: description: >- Unique within its workflow. Named in results and admission errors, and in `${step..}` references from later operations. type: string invocation: description: 'Runs the operation once per member of a list. Absent: one request.' oneOf: - $ref: '#/components/schemas/ProviderInvocation' - enum: - null nullable: true type: object outcomes: description: >- Ordered outcome rules; the first rule whose predicates all hold decides. items: $ref: '#/components/schemas/ProviderOutcomeRule' type: array request: $ref: '#/components/schemas/ProviderRequestTemplate' description: The request to send. required: - id - request - outcomes type: object ProviderSignedToken: description: >- A short-lived JWT a check signs from the strategy's credential, for a provider whose sign-in takes a token the client mints itself, such as a Tableau Connected App. Requests read it as `${signed.}`; it is secret, so it goes only in a header that carries a credential or as a whole string value of a sign-in body. It is minted fresh for each request: the executor adds `exp` (now plus lifetimeSeconds) and a random `jti`, and sets the JOSE header's `alg` and `typ`. The signing key never enters the token, a URL, a log or a result. properties: algorithm: $ref: '#/components/schemas/ProviderSigningAlgorithmEnum' description: How the token is signed. claims: description: >- The claims, as a JSON object. A member is a string, which may hold the same references as a header value, a number, a boolean, or a list of strings. The executor sets `exp` and `jti`; neither they nor `iat` and `nbf` may be declared. headers: additionalProperties: type: string description: |- JOSE header members besides `alg` and `typ`: only `kid` and `iss`. A value may hold `${credential.}` and non-secret `${ingestion.}` references. nullable: true type: object key: description: |- The credential field holding the signing key. It must be declared x-secret, and no claim or header value may reference it. type: string lifetimeSeconds: description: How long the token is valid, from 1 to 600 seconds. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer name: description: Unique within the workflow; the name `${signed.}` reads. type: string required: - name - algorithm - key - lifetimeSeconds - claims type: object CredentialProbeWriteback: description: |- An extracted value a successful workflow stores in the connection's ingestion config, the way a Tableau sign-in records the site id. Only an extract declared `secret: false`, of type string, may be written, and only to a declared, non-URL, string ingestion field. properties: extract: description: The extract's name within that operation. type: string operation: description: The id of the operation that extracts the value. type: string target: description: The top-level ingestion config field the value is written to. type: string required: - operation - extract - target type: object OAuthGrantType: description: OAuth 2.0 grant type for token requests. enum: - client_credentials - authorization_code - refresh_token - account_credentials type: string BodyEncodingEnum: description: Serialization of a POST/PUT/PATCH request body for a REST endpoint. enum: - json - form type: string TokenEndpointAuthMethod: description: How client credentials are sent to the OAuth2 token endpoint. enum: - client_secret_basic - client_secret_post - none - basic_credentials type: string ProviderExtract: description: >- A value an operation reads from its response once a success rule matches. A workflow writeback can store it in the connection's ingestion config. A secret value never enters a URL, a log, a result detail, or a writeback. properties: name: description: >- Unique within its operation; a writeback names it with the operation id. type: string secret: description: >- Whether the value is secret. Absent means secret: only an extract that declares `secret: false` may be written back. nullable: true type: boolean source: $ref: '#/components/schemas/ProviderValueRef' description: >- The response value: `status`, `headers.`, or `body.`. type: $ref: '#/components/schemas/ProviderExtractTypeEnum' description: >- The JSON type the value must have; a value of another type, a value the bounded read cannot reach, or a value over 2048 bytes is not extracted. required: - name - source - type type: object ProviderInvocation: description: >- Runs an operation once per member of a list, a bounded number of times. Each member is one request, counted against the workflow's request budget; the request reads the member as `${item.}`. properties: aggregation: description: >- How member outcomes combine into the operation's outcome. Defaults to all_success. oneOf: - $ref: '#/components/schemas/ProviderAggregationEnum' - enum: - null nullable: true type: string forEach: $ref: '#/components/schemas/ProviderValueRef' description: >- The list to iterate: an `ingestion` field declared as a list of strings or numbers. itemName: description: The name the request uses for the current member. type: string maxItems: description: >- Most members to run, from the start of the list. Required: an iteration without a bound is refused. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer required: - forEach - itemName type: object ProviderOutcomeRule: description: >- An outcome that applies when every predicate holds. Rules are tried in order and the first match wins; a predicate the response cannot decide (a body read only in part) never holds. properties: all: description: Conditions that must all hold. items: $ref: '#/components/schemas/ProviderPredicate' type: array outcome: $ref: '#/components/schemas/ProviderOutcomeEnum' description: What a match means. reason: description: Why, in words a reader of the result can act on. nullable: true type: string required: - all - outcome type: object ProviderRequestTemplate: description: The request an operation sends. properties: allowedConfiguredHost: description: >- An ingestion field declared as a Network.Url, not secret, whose host the request may also go to, exactly: a self-hosted provider the connection is configured to reach. The suffixes above still apply to every other host, and the host must still be public. A Workspace editor can change the field, so the request then carries the credential to any public host the editor saves. nullable: true type: string allowedHostSuffixes: description: >- DNS suffixes the resolved endpoint host may use. Matching is on a label boundary, so `api.example.com` matches `example.com` and `notexample.com` does not. items: description: Valid domain name (RFC 1035 compliant) maxLength: 255 pattern: >- ^[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?)*$ type: string type: array auth: $ref: '#/components/schemas/ProviderRequestAuth' description: How the request is authenticated. defaults: additionalProperties: type: string description: >- Literal values for referenced configuration fields that are absent or empty, keyed `ingestion.` or `credential.`: the value the provider or sync assumes when the field is left blank and no schema default supplies it (Tableau's `apiVersion` 3.29, its Default site `""`). An ingestion field's schema default applies before these. Each key names a declared, non-secret field the request references. A default is catalog text, not configuration, yet it takes its field's taint and placement rules. Only a declared default may be empty, and never in the endpoint. A default for a field that supplies the base URL must be an absolute https URL without a query or fragment, under allowedHostSuffixes. nullable: true type: object endpoint: description: >- One of: an absolute https URL with references in its path and query; one reference to an ingestion field declared as a Network.Url (the whole URL comes from configuration); that reference followed by a path or query (`${ingestion.baseUrl}/api/3.29/auth/signin`); or an https URL whose host starts with one non-secret ingestion field used as a DNS label (`https://${ingestion.tenantName}.workday.com/...`), when the literal rest of the host lies under an allowed suffix. Every form is checked against the allowed destinations once resolved, before anything is sent. type: string fallbackEndpoint: description: >- The endpoint used when the configured URL `endpoint` starts with is absent or empty: the provider's fixed host, for a connection that overrides it only when set (Workday's optional `baseUrl` in place of `https://${ingestion.tenantName}.workday.com`). Only an endpoint that starts with a `${ingestion.}` reference with no default may declare one. It is an absolute https URL, or the host-label form, never a configured URL itself, and its host must lie under allowedHostSuffixes: allowedConfiguredHost does not admit it, because the configured field is empty whenever it is used. nullable: true type: string headers: additionalProperties: type: string description: >- Request headers by name. A value may hold `${ingestion.}` references, and `${credential.}` references only in a header whose name says it carries a credential (Authorization, Cookie, or a name containing token, key, auth, secret, session, password, signature or credential). A header the transport or the strategy's auth sets is refused. nullable: true type: object method: $ref: '#/components/schemas/HttpMethodEnum' description: >- HTTP method: GET, or POST for providers whose check is a call (Slack's auth.test, a GraphQL query). queryParams: additionalProperties: type: string description: >- Query parameters added to the endpoint's query, by name. A value may hold `${ingestion.}` references, never a credential. nullable: true type: object replaySafe: description: >- Whether the request may be sent again when a rule answers retry. A GET always may; a POST only when declared safe (a read-only query), so a single-use exchange is never replayed. nullable: true type: boolean requestBody: description: >- A JSON body for a POST, sent as application/json unless the strategy's extraHeaders set another content type. A string value may hold `${ingestion.}` references. A `${credential.}` reference is allowed only when auth mode is `body` (a sign-in) and must be a whole string value. nullable: true required: - method - endpoint - allowedHostSuffixes - auth type: object ProviderSigningAlgorithmEnum: description: How a check signs a token it mints. enum: - HS256 type: string ProviderValueRef: description: >- A declarative provider operation: one bounded request and the ordered rules that read its response. Request strings carry references in the `${namespace.path}` form, for example `${ingestion.customReportUrl}`. A value a predicate or an extract reads, or the list an iteration runs over. properties: namespace: $ref: '#/components/schemas/ProviderValueNamespaceEnum' description: The source of the value. path: description: |- Where in the namespace. For `response`: `status`, `text`, `headers.`, `body`, or `body.`. type: string required: - namespace - path type: object ProviderExtractTypeEnum: description: >- The JSON type an extract requires of the value it reads. A value of another type is not extracted. enum: - string - number - boolean type: string ProviderAggregationEnum: description: How the members of an iterated operation combine into its outcome. enum: - all_success - any_success type: string ProviderPredicate: description: One condition on a value. properties: expected: description: >- The operand: a scalar for equals, not_equals and contains, a [low, high] pair for between, a list for any_of, and null for exists, not_exists, empty and non_empty. nullable: true operator: $ref: '#/components/schemas/ProviderPredicateOperatorEnum' description: How the value is compared. source: $ref: '#/components/schemas/ProviderValueRef' description: The value the condition reads. required: - source - operator type: object ProviderOutcomeEnum: description: >- Vocabulary of a declarative provider operation: one bounded request to a provider and the ordered rules that turn its response into an outcome. Credential validation is the first consumer; each consumer maps an outcome to its own verdict. What a matched outcome rule says about the request. enum: - success - expected_empty - retry - auth_rejected - permission_denied - config_invalid - upstream_failure type: string ProviderRequestAuth: description: How the request is authenticated. properties: mode: $ref: '#/components/schemas/ProviderRequestAuthModeEnum' password: description: 'Auth mode `basic` only: the credential field holding the password.' nullable: true type: string username: description: 'Auth mode `basic` only: the credential field holding the user name.' nullable: true type: string required: - mode type: object HttpMethodEnum: description: HTTP method for API calls. enum: - GET - POST - PUT - PATCH - DELETE type: string ProviderValueNamespaceEnum: description: Where a reference reads its value from. enum: - credential - ingestion - clock - item - step - response - signed type: string ProviderPredicateOperatorEnum: description: How a predicate compares the value it reads. enum: - equals - not_equals - between - any_of - exists - not_exists - empty - non_empty - contains type: string ProviderRequestAuthModeEnum: description: How a provider operation request is authenticated. enum: - none - strategy - body - basic 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.