---
title: "Connector"
description: "A Connector connects a Flow to an external provider, such as an email,"
canonical_url: "https://docs.superdurable.io/concepts/connector/"
source: "docs/content/concepts/connector.mdx"
locale: "en"
---

# Connector

A **Connector** connects a Flow to an external provider, such as an email,
payment, or news service. It gives your Flow ready-made Steps that call the
provider, and Triggers that turn provider events into Flow starts or RPC calls.
Your application imports a Connector package and uses its Steps like your own.
Provider credentials never enter durable Flow state.

Official Connectors are released separately from Dex. Before you write
provider integration code yourself, [find a Connector](https://docs.superdurable.io/concepts/connector.md#find-a-connector) for
that provider.

## Capabilities

A Connector can expose five capabilities:

- **Auth** authorizes a named connection to the provider.
- **Trigger** turns a provider event into a typed event. The event can start a
  Flow or call a typed RPC.
- **Query** reads provider state from a Connector Step.
- **Mutation** changes provider state. It sends an idempotency key and handles
  calls whose outcome is unknown.
- **UI** supplies reusable configuration units. Dex Web combines them into the
  settings form for a Step or a Trigger binding.

A Connector exposes only the capabilities its provider needs. Your application
uses the types generated for the exact Connector release it imports.

<a id="operations-are-connector-steps"></a>

## Operations are ready-made Steps

Each operation has a factory that creates a Connector Step. Your application
maps the current Step input to the provider input. It connects each required
result branch to another Step. The provider call runs in **Execute**, so it
gets Dex retries, timeouts, durability, and recovery like any other
[Step](https://docs.superdurable.io/concepts/step.md).

A Connector result contains the operation output, a receipt, the selected
branch, and a safe failure classification when one exists. The result does not
carry the previous Step input forward. Keep business context in an
[Attribute](https://docs.superdurable.io/concepts/primitives/attribute.md), or pass it through an application
Step before the Connector.

Only the happy-path branch must be connected. You can leave optional branches
unconnected. If the Connector selects an unconnected branch, the Flow fails.
The provider outcome stays visible for recovery.

<a id="queries-and-mutations"></a>

<a id="effect-classes"></a>

### Effect classes

Each operation is a Query or a Mutation. A Query reads provider state. A
Mutation changes it. Each operation has an effect class that says what a
repeated call does:

| Effect class         | Operations                                         | What a repeated call does                                                                                                    |
| -------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Read                 | Every Query                                        | Changes nothing.                                                                                                             |
| Idempotent write     | A Mutation that its Connector marks safe to repeat | Makes no second effect. The Connector author has confirmed that the provider ignores a repeat with the same idempotency key. |
| Non-idempotent write | Every other Mutation                               | Can make a second effect.                                                                                                    |

A Mutation sends the same idempotency key every time Dex retries its Step.

When a Mutation's outcome is unknown, the Connector selects an uncertainty
branch. Connect it to a Step that queries the provider and reconciles. Do not
send the Mutation again blindly.

## Triggers start or update Flows

A Connector Trigger is a long-running event source outside the Flow. It keeps
the provider event ID and occurrence time. It delivers each event at least once
to a target that your application owns.

Your application supplies the final filter, resolves the Flow ID, and maps the
provider event to a typed input. It chooses whether the event starts a Flow or
calls a typed [RPC](https://docs.superdurable.io/concepts/primitives/rpc.md) on an existing Flow. A Flow start
uses the provider event ID as its request ID, so a repeated event does not
start a second Flow. An RPC target must handle duplicates itself, in its own
bounded state.

Local Trigger runners save a matched event before they acknowledge it to the
provider. After a restart, they deliver the events that were still pending.

<a id="connections-and-configuration"></a>

## Connections

A connection is a named, authorized account at a provider. Flow definitions
refer to a connection by its name, not by its credentials. Your application
resolves the name to credentials when it calls the provider.

Stored credentials never enter Flow input, Attributes, results, receipts,
Streams, logs, or generated artifacts.

## Languages

Connectors support Go, Python, and TypeScript. Java and Rust do not support
Connectors yet. Each language package implements only the operations and
Triggers that the Connector lists for that language. Use the language filter in
the [Connector catalog](https://connectors.superdurable.io/) to see what each
Connector offers.

Go packages are the Go module of each Connector. Python packages are on PyPI as
**dex-connector-\<slug>**. TypeScript packages are on npm as
**@superdurable/connector-\<slug>**. Every Python and TypeScript package
is tested against the same provider scenarios that verify the Go package.
Runnable examples are under
**connectors/\<directory>/\<language>/examples/** in the
[Dex Connectors Library](https://github.com/superdurable/dex-connectors-library).
If you need another language,
[open a Dex Connectors Library issue](https://github.com/superdurable/dex-connectors-library/issues/new).

<a id="use-or-contribute-a-connector"></a>

<a id="how-it-fits-with-the-other-components"></a>

## Find a Connector

Browse the [Connector catalog](https://connectors.superdurable.io/). It lists
each released Connector, its operations, and its language support. The catalog
is the reference for each Connector.

The [Dex Connectors Library](https://github.com/superdurable/dex-connectors-library)
contains manifests, generated APIs, provider implementations, UI units, and
runnable examples.

Use the [Dex SDK skill](https://docs.superdurable.io/build-with-ai/dex-developer-skill/dex-sdk.md) when an
application uses a released Connector. Use the
[Dex Connector Contributor skill](https://docs.superdurable.io/build-with-ai/dex-developer-skill/dex-connector-contributor.md)
to add or change an official Connector, operation, Trigger, or UI unit.

## Set up Connectors locally

For local development, [Dex Web](https://docs.superdurable.io/components/web.md) configures Connector
connections and Trigger bindings for a Go application. It does this only in
**dexcli dev**.

1. Start **dexcli dev** with your Flow Definition Graph directory.
2. Open the **Connectors** page in Dex Web. It lists the connection names that
   your Flow definitions use. Authorize each one.
3. Start your application with the connection file that Dex Web shows.

To use a connection that no Flow definition names, such as one an agent tool
uses, add it by name on the same page. Then authorize it like any other.

Dex Web configures only the exact official Connector release. A Connector's UI
runs in a sandboxed iframe, and stored credentials never enter it.

The connection file holds plaintext secrets for local use only. Do not commit
it or use it in production.

[Local Connector setup](https://docs.superdurable.io/reference/web/local-connector-setup.md) describes each step
and its settings.