# How connectors work

<Term id="connector">Connectors</Term> link your team's tools to your <Term id="workspace">workspace</Term>. A <Term id="project">project</Term> can read from them, bring data into <Term id="nexus">Nexus</Term>, and send results back.

## Two ways to connect [#two-ways-to-connect]

| | GitHub (native) | Every other connector (AI) |
| --- | --- | --- |
| **Who connects it** | A workspace owner or admin, once for the whole workspace | Anyone working in a project, with that project's AI |
| **How** | Install the Klarety app on GitHub and choose repositories | The AI drafts the connection; you finish it with your key or sign-in |
| **Where it is used** | Every project can link one of the chosen repositories | The project it was made in, plus projects an admin switches on |

The [GitHub guide](/docs/connectors/github) covers the native connector. This page covers the AI flow.

## How the AI connects a service [#how-the-ai-connects-a-service]

### 1. You ask [#1-you-ask]

<ForEveryone>
Open a connector on <AppLink to="connectors" /> and use **Connect it with your Studio's AI**: pick a **Project**, check **What the AI is asked**, and select **Send to AI**. Or, inside a project, go to **Settings**, then **Keys**, and use **Ask AI to connect**.

<Screenshot src="/docs/_media/connect-data-with-ai-in-dashboard-data-page.png" alt="A connector page with Connect it with your Studio's AI, the Project picker and Send to AI" />
</ForEveryone>

<ForDevelopers>
```python title="ask_ai.py"
from klarety import Nexus

nx = Nexus.connect("YOUR_API_KEY")
nx.service_connections.ask_ai("PROJECT_ID", "Connect Stripe so it can read payments")
```
</ForDevelopers>

### 2. The AI drafts the connection [#2-the-ai-drafts-the-connection]

The AI works out the site, the kind of key and how to get one. The draft holds no key, reaches nothing, and shows as **Waiting for you**.

<Callout type="info" title="The AI never asks for a key in the chat">
  Never paste a key into a chat. Keys go only in the connect dialog.
</Callout>

### 3. You finish it [#3-you-finish-it]

Select **Connect**. The dialog asks for one of:

- a **Key**, with **Open the page with your key** to get one;
- a **User name** and **Password**, for databases;
- a sign-in with the provider, for services such as Google and Microsoft.

Choose **What the AI may do with it**: **Can read** or **Can read and change**. Then select **Connect**, **Test it** and **Tell the AI**.

<Screenshot src="/docs/_media/slack-connector-how-to-connect-in-ui.png" alt="The connect dialog asking for a key" />

### 4. The project uses it [#4-the-project-uses-it]

The <Term id="studio">Studio</Term> calls the service and your key is added on the way out. The key never enters the Studio.

## What keeps your keys safe [#what-keeps-your-keys-safe]

- **Sealed at once.** Encrypted with a managed key service the moment you select **Connect**. Nobody, including the AI, can read them back.
- **One site only.** The dialog shows the only site the key is sent to. If it is not the service's own address, Klarety warns you and asks you to type it to confirm.
- **Least access.** Choose **Can read and change** only when the job needs it.
- **Internet setting.** A project whose internet is **Off** cannot use connections. With **Only allowed**, its Studio reaches only its connections and the sites you add.

## See and manage connections [#see-and-manage-connections]

<ForEveryone>
In a project, open **Settings**, then **Keys**. Each connection shows **Waiting for you**, **Works**, **Needs reconnecting** or **Paused**, with **Connect** or **Reconnect**, **Test**, **Pause** or **Resume**, **Turn off here** and **Remove**.

Owners and admins also see **Your connections** on <AppLink to="connectors" />. A connection stays off for other projects until an admin switches it on.

<Screenshot src="/docs/_media/project-page-nexus-data-connections.png" alt="A project's connections map, showing each connection and table with its access" />
</ForEveryone>

<ForDevelopers>
```python title="manage_connections.py"
from klarety import Nexus

nx = Nexus.connect("YOUR_API_KEY")

listed = nx.service_connections.list("PROJECT_ID")
for connection in listed["connections"]:
    print(connection["name"], connection["health"])

result = nx.service_connections.check("PROJECT_ID", "CONNECTION_ID")
print(result["result"], result["detail"])

nx.service_connections.change("CONNECTION_ID", paused=True)
nx.service_connections.switch("CONNECTION_ID", "OTHER_PROJECT_ID", on=True)
```

`health` is one of `waiting`, `works`, `needs_reconnecting` or `paused`. `check` returns `result` as one of `works`, `key_rejected`, `cannot_reach`, `internet_off` or `not_connected`, with a readable `detail`, never the key. `org()` lists every workspace connection and `switch` turns one on for a project (owners and admins only).
</ForDevelopers>

## Webhooks [#webhooks]

A service can call your project when something happens. In **Settings**, **Keys**, select **Add webhook**, give the service the address Klarety shows, and paste its signing secret. Klarety verifies every call. See the [Stripe guide](/docs/connectors/stripe) for an example.

## Next steps [#next-steps]

- [All connectors](/docs/connectors/catalog)
- [GitHub](/docs/connectors/github)
- [Amazon S3](/docs/connectors/amazon-s3)
- [PostgreSQL](/docs/connectors/postgresql)