Integrations
Integrations manages third-party connections and connection diagnostics.
Integrations connect a workspace to third-party provider accounts and provider-backed product functions. Use this page before a run needs a connection, then return to the pack that owns the intended result, such as a workbook, a CRM record, a sequence, or a social post.
The integrations pack owns authorization, credentials, connection health, diagnostics, and synchronization. It does not own sender identity or suppression policy, which belong to Senders and mailboxes, and it does not own the external-provider marketplace, which is described in Marketplace.
What integrations own
An integration is the connection boundary between one workspace and a third-party provider account. The integrations pack owns connecting and disconnecting provider accounts, connector authorization, OAuth credentials and refresh tokens, provider health, connection diagnostics, and synchronization of workspace records or rows with a connected system.
This division prevents a connection problem from being mistaken for a data problem. For example, the CRM pack owns durable record truth, while integrations owns the provider connection behind a CRM. Social owns publishing and audience results, while integrations owns the credential needed to reach a social provider. Visibility owns measurement results, while integrations owns the provider setup behind connected analytics.
In the app, connection handoffs point to Settings, including the Integrations tab. Provider-specific catalog entries can instead point to the relevant settings destination, such as the outreach or LinkedIn settings area. The returned web_url, when present, is the app location for the created or state-bearing result; the JSON identifier remains the durable value for an API client.
Architect uses the same capability catalog as the other product surfaces. It can search for the integration capability, retrieve the exact schema, and then run the discovered contract. Do not assume that a profile in the public marketplace is itself a runnable operation or proof that the current workspace has access.
| Connection kind | When it appears | What stays separate |
|---|---|---|
| OAuth connection | The provider opens its authorization flow. | The connection is scoped to the workspace and provider. |
| Provider credential | A provider requires a protected credential. | The credential travels through a secret lease, not a tool parameter. |
| Managed provider | Dreamstate supplies a provider-backed product function. | Availability still depends on workspace configuration. |
| Connection handoff | A catalog capability returns the settings destination. | The browser completes the provider-specific setup. |
Discover connection readiness
Start with the provider catalog rather than naming an undocumented command or passing a guessed schema. The active catalog includes integrations.providers_list for the currently connectable providers and integrations.connect_start for a connection handoff. The handoff is synchronous, free, idempotent, and records an internal reversible connection-handoff result.
A connection handoff resolves the selected provider for the workspace and returns the settings URL where the browser flow continues. An unknown or unavailable provider is rejected as invalid_request with a message that its provider_id is not connectable in that workspace catalog. Treat that as a catalog and workspace-state problem, not a reason to invent a provider identifier.
The public integration registry currently distinguishes connection types such as OAuth, workspace API keys, provider credentials, Dreamstate-managed providers, mailbox OAuth, and source-specific setup. It lists profiles for LinkedIn, X, Google Search Console, Google Analytics 4, HubSpot, Slack, mailboxes, GitHub, WordPress, Framer, and other products. A profile states the intended product relationship, not an entitlement promise for every workspace.
Missing connections block the provider-backed execution that needs them, but they do not block building a workbook, sequence, workflow, or other workspace system. Build the structure and validate its local state first. Connect the account when the work reaches a provider-backed step, then re-run discovery so the agent reads the current contract rather than relying on an earlier readiness result.
Find the connection needed to synchronize this workspace with HubSpot. Show the current readiness and the Settings destination. If it is not connected, tell me which workbook and CRM preparation steps can proceed without it.Credentials and browser handoffs
Credentials are not ordinary capability parameters. Several root-action schemas accept a secret_lease_id, which refers to a pre-staged protected lease. The documentation in those schemas says that the credential itself never travels in parameters and is available only inside the lease callback. Keep passwords, access tokens, and API keys out of prompts, copied request JSON, and shell history.
OAuth starts can be provider-specific. The mailbox OAuth start accepts only gmail or outlook and returns a single-use authorization_reveal_path that is valid for 120 seconds; the mailbox is not usable until the consent callback completes. CRM OAuth setup supports HubSpot, Attio, and Salesforce, while a deployment missing its client credentials returns a provider-specific <provider>_oauth_not_configured error.
A LinkedIn native connection expects a protected lease and an uppercase two-letter ISO country code. Its account type defaults to member. If the provider asks for a checkpoint, the follow-up uses the returned pending identifier and another protected lease. An unknown or expired pending identifier returns linkedin_checkpoint_not_found, so restart the connection flow rather than trying to reuse an old checkpoint.
The scheduler connection can be scoped to a sender account or be workspace-wide. Slack connection setup has a default_mode that defaults to architect; using draft limits Slack to producing drafts. These are provider-specific contracts, so inspect the schema returned for the exact capability before choosing fields or defaults.
Connection effects and cost
A catalog entry exposes its own action policy, cost policy, asynchronous policy, required scopes, and schema. Read that entry before a live run. The catalog uses only the credit classes free, action, and dynamic; connection setup is not a substitute for checking the cost of the later provider-backed action.
When a live capability needs a price, the system returns quote_required with its estimate. Re-run the same call with unchanged parameters and a max_credits ceiling. That ceiling applies to the run, while the provider's external billing relationship remains governed by the provider connection. See Credits and billing for the quote and run-budget model.
Connection, disconnection, credential, and other owner actions are security-sensitive. They run from a signed-in session, never from an API key, require a fresh approval at the applicable tier, and require an Idempotency-Key. This security exception controls access to workspace ownership and external reach. It is not a spend approval step. The exact tier may be fresh_owner, workspace_admin, or current_member for mailbox authorization.
A provider-backed run can be read-only, internally reversible, externally sending, publishing, enrolling, activating, or test-running according to its catalog policy. Read the specific contract before treating a provider call as safe to retry. A calendar event create or update, for example, can contact invitees through the connected Google calendar, while a local events list reads stored workspace rows without calling a provider.
When it goes wrong
If discovery returns invalid_request for a provider identifier, search the current provider catalog and select only a provider that is connectable in this workspace. The provider may be absent because the workspace has no enabled catalog entry, not because a different spelling will work.
If an OAuth start reports <provider>_oauth_not_configured, the deployment lacks the client credentials for that provider. Stop the setup attempt and use a provider that the workspace actually exposes, or ask the workspace owner to resolve the provider configuration. Do not enter a secret in a tool argument as a workaround.
If a mailbox authorization path expires, start a new mailbox OAuth handoff. If LinkedIn returns linkedin_checkpoint_not_found, restart the native connection flow because the pending value is unknown or expired. If a protected lease is invalid, reacquire the lease through the authenticated flow instead of retrying the same identifier indefinitely.
If a provider call finishes externally but its local finalize step fails, the result can be reconciliation_required. For calendar writes, that response is a 409 and does not trigger an automatic retry. Inspect the provider state and the local result before retrying so a second action does not duplicate an external event or notification.
If the failure is a missing connection, return to the settings handoff, complete it, and rediscover the tool schema. If the failure is a recipient, sender, sequence, or suppression rule, leave the provider connection alone and investigate the owning pack. This boundary is the fastest way to avoid changing credentials when the real problem is in outreach policy or application data.