Concepts
Concepts
Section titled “Concepts”Connect is the one place your workspace authorizes external services. Instead of every Destesi product asking you to paste in a GitHub token, a Slack token, and a stock-media key, you connect each service once in Connect, and products fetch the live credential at the moment they need it.
Connect does three things, and they build on each other:
| What it is | |
|---|---|
| Connection | Permission — a stored, workspace-scoped credential for one external account. |
| Action | A single typed operation you run against a connection, with the credential injected server-side. |
| Trigger | The reverse direction — a provider’s webhook, verified and forwarded to your endpoint, signed. |
This page covers the mental model. For the concrete provider list, API, and error codes, see the Reference.
Why a single credential hub
Section titled “Why a single credential hub”Storing the same secret in three products means rotating it in three places, three blast radii if one leaks, and three different “reconnect” prompts when a token expires. Connect collapses that to one:
- Connect once. Authorize a service from the Connect catalog. The credential is stored once, workspace-scoped.
- Fetch at call time. When a product needs to act — Chat sending an email, Studio publishing a video, Preview cloning a repo — it asks Connect for the current credential and calls the provider itself.
- One reconnect. If a token expires or is revoked, you reconnect in Connect, and every product is healthy again.
Connectors and connections
Section titled “Connectors and connections”- A connector is Connect’s built-in support for one provider — Slack, GitHub, YouTube, Pexels, and so on. Each connector knows how to run that provider’s authorization flow, refresh its tokens, and validate that a stored credential still works. The full catalog is published at the catalog endpoint and rendered in the Connect UI.
- A connection is the result: a stored, workspace-scoped credential for one provider (and, for multi-account providers, one downstream account). A connection carries account metadata (username, display name, avatar) and a status — but the secret itself is never returned to the browser.
The catalog spans ten categories and more than fifty providers:
| Category | Examples |
|---|---|
| Dev tools | GitHub, GitLab, Bitbucket, Slack, Linear, Jira, Asana, ClickUp, Notion, Trello, Sentry, Vercel, Cloudflare |
| Social | YouTube, Instagram, Facebook, Threads, TikTok, LinkedIn, Pinterest |
| Advertising | Meta Ads, Google Ads |
| Communication | Gmail, WhatsApp Business, Discord, Microsoft Teams, Zoom, Cal.com |
| CRM | Salesforce, Pipedrive, Intercom |
| Storage | Google Drive, Google Sheets, Dropbox |
| Stock media | Pexels, Pixabay, Unsplash, Freepik, Shutterstock |
| AI | OpenAI, Anthropic, Cohere, Replicate, Hugging Face, Stability, ElevenLabs |
| Commerce | Stripe, PayPal, Wompi, Skydropx |
| Cloud | AWS |
A provider that isn’t currently available is shown with the reason rather than quietly hidden, so you can tell “not built yet” apart from “temporarily unavailable”.
Ways to authorize
Section titled “Ways to authorize”You click Connect, get redirected to the provider’s own consent screen, approve the scopes, and the provider redirects you back. Connect exchanges the authorization code for tokens, stores them, and (for OAuth providers) refreshes them on your behalf as they near expiry. You never see or handle the token.
API key
Section titled “API key”Some providers — the AI providers, stock media, Cal.com, Wompi, Skydropx — authenticate with a long-lived API key rather than OAuth. You paste the key into Connect’s Add API key modal. Before saving, Connect calls the provider to validate the key — if the provider rejects it, the key is refused and nothing is stored. A valid key is saved as an api_key connection.
Because these need no application registered on Destesi’s side, they are connectable in any deployment: you bring your own key.
Cloud role
Section titled “Cloud role”AWS works differently, and deliberately. Rather than holding your access keys, Connect asks you to run a one-click CloudFormation stack in your own account. That creates a role Destesi can assume, scoped to what the product actually needs and guarded by a secret unique to your workspace. Credentials are minted fresh for each call and never stored. You can revoke access by deleting the stack — no key rotation on our side required.
Embedded signup
Section titled “Embedded signup”WhatsApp Business uses a provider-run flow that provisions the business account as part of connecting, rather than a plain consent screen.
Multi-account
Section titled “Multi-account”A single OAuth grant can expose several downstream accounts: one Google login can manage many YouTube channels, several Gmail mailboxes, or several Drive and Sheets accounts; one Meta login can manage many Instagram business accounts, Pages, and ad accounts.
For these providers Connect runs the authorization in two stages:
- You approve the provider’s consent screen.
- Connect lists the accounts that grant exposes and shows you a picker. You choose which accounts to add — one connection is created per account.
You can flag one account as the default for that provider. When a product asks Connect for “the YouTube credential” without naming an account, it gets the default. Accounts in the Connect nav is where you review and change those defaults later.
Single-account providers skip the picker entirely.
Connection status
Section titled “Connection status”Every connection has a status (the API reports it in uppercase) so products and you both know its health:
ACTIVE— the credential works.ERROR— a product reported that the provider rejected the credential.EXPIRED— an OAuth token expired and could not be refreshed; you need to reconnect.REVOKED— an API key was rejected by the provider on a health re-check; you need to re-add it.PENDING— an AWS connection whose CloudFormation stack has not been deployed yet. Pending connections are hidden from your connections list until they complete, because a half-finished connection is not something a product can use.
You can re-check a connection’s health from the Connect UI at any time, which pings the provider and updates the status.
Actions
Section titled “Actions”A connection is permission; an action is what you do with it. Each action has a stable id of the form {provider}.{action} — github.create_issue, slack.post_message, google_drive.delete_file — and that id never changes once shipped, so anything built on it keeps working.
Every action declares its side effect, and the label is the honest one:
- read — fetches something and changes nothing.
- write — creates or modifies something at the provider.
- destructive — deletes something. Only a handful of actions are destructive, and they say so before you run them.
Why actions are safer than handing over a token
Section titled “Why actions are safer than handing over a token”The alternative — giving a product your raw token and letting it call whatever URL it likes — is exactly what an action prevents. When you run one:
- You supply only typed arguments, validated against the action’s schema before anything happens. An argument the action didn’t declare is rejected outright rather than passed along.
- The destination is fixed by the action, not by you. Each action carries its own host, and Connect verifies the assembled URL still points there before making the call. There is no argument you can set that redirects the request somewhere else.
- The credential is injected server-side and stripped from both the result and any error message. It doesn’t appear in what you send or in what you get back.
- Redirects are disabled, requests time out, and large responses are truncated with a flag rather than streamed back whole.
Some actions need several calls to the provider to complete — publishing a video to LinkedIn, for example, has to negotiate an upload, transfer the bytes, then create the post. Those run server-side as one action, and they pass through every check above before the first call goes out.
Triggers
Section titled “Triggers”A trigger is the inbound direction: a provider tells Connect something happened, and Connect forwards it to an endpoint you control.
The flow separates two secrets that are easy to confuse:
- The ingest token in the URL is only a routing handle. It says which subscription a delivery belongs to, and it is never logged.
- The inbound secret is the authenticator. Connect verifies every incoming delivery’s signature against it, and rejects anything that doesn’t match.
Once verified, the delivery is recorded and forwarded to your endpoint with a third secret — the signing secret — used to sign the outgoing request. Your endpoint verifies that signature to know the delivery really came from Connect. The signature covers a timestamp as well as the body, so a captured delivery can’t be replayed at you later.
Failed deliveries retry with growing backoff before being marked failed, and you can see what happened to each one. Connect does not register the webhook at the provider for you: it hands you the URL and the inbound secret, and you paste them into the provider’s settings.
What the guard refuses
Section titled “What the guard refuses”Connect will only deliver to an HTTPS endpoint on the public internet, and it checks twice — when you create the subscription, and again at the moment it dials. It refuses addresses inside private networks, loopback, and link-local ranges, and it pins the address it verified so a name can’t resolve to something else between the check and the call. This is what stops a trigger from being turned into a way to reach into a private network.
How products fetch credentials
Section titled “How products fetch credentials”Products never see your secret in a way you’d recognize. Two paths exist:
- In the browser, the Connect UI lists your connections with account metadata and status only — tokens are always scrubbed.
- Server-side, a sibling product backend calls Connect’s controller API (or one of the SDKs) with a shared controller secret to fetch the live credential, then calls the provider directly. OAuth tokens are refreshed on demand at this point; if refresh fails, the connection flips to
EXPIREDand the product can prompt you to reconnect.
This is why connecting a service in Connect is all you ever do: the products take it from there.
What the agent will and won’t do
Section titled “What the agent will and won’t do”Connect’s own chat manages all of the above in conversation. Two boundaries hold, and they are enforced in code rather than left to the model’s judgement:
- It cannot show you a secret. Connections, triggers, and results are redacted before the agent ever sees them. Trigger secrets are revealed exactly once, by you, through an explicit reveal — and once revealed they cannot be read again. If you lose them, you create a new subscription.
- Read runs; write asks. The agent can run read-only actions directly. Anything that writes — a write action, creating or pausing or deleting a trigger — pauses for your approval and only proceeds when you confirm. An approval is single-use and expires.
How Connect fits the suite
Section titled “How Connect fits the suite”Connect is one of the platform products that tie the whole suite together, alongside Accounts (one login) and Drive (one library). The flow across the suite is credentials in, artifacts out: products pull third-party credentials from Connect at call time and register everything they produce in Drive.