> ## Documentation Index
> Fetch the complete documentation index at: https://klef.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector SDK

> Write a connector for a system Klef does not cover, and run it on your own network.

Klef ships connectors for the systems in [Connectors](https://klef.ai/docs/connectors.md). For anything else, such as an in-house app, an on-premises directory or a SaaS app Klef does not cover yet, you can write your own connector with the Klef connector SDK.

A connector you write belongs to your workspace. It uses the same manifest format, the same contract and the same plans as Klef's own connectors, so its accounts, grants and changes read like any other connection.

## How It Works

> [card] A manifest
>
> `connector.yaml` declares what the connector reads and writes: its connection fields, how it authenticates, the hosts it calls, and the fields of an account.

> [card] Code on the SDK
>
> A C# project on the `Klef.Connectors.Sdk` package implements the target or source contract. The SDK's HTTP client applies the manifest's auth, egress and limits for you.

> [card] Tests from the kit
>
> The `Klef.Connectors.Testing` package runs conformance and a full provisioning journey against your own test tenant.

> [card] A connector on your network
>
> Your connector runs on a machine you host and serves its calls over HTTP there. Klef's relay runs beside it and calls out to Klef over HTTPS, so Klef never connects in, never loads your code, and never holds your connector's credentials.

## The Tools

| Package | What it is |
| - | - |
| `Klef.Cli` | The `klef` command line. `klef connectors` scaffolds, validates, tests, pushes and serves a connector, and `klef relay` connects it to Klef. |
| `Klef.Connectors.Sdk` | The contracts, the HTTP and SCIM clients, and the manifest's generator. |
| `Klef.Connectors.Model` | The records a connector reads and writes, such as `Principal` and `SourceWorker`. |
| `Klef.Connectors.Testing` | The conformance kit and the journey. |
| `Klef.Connectors.Runner` | What `klef connectors serve` uses to serve a connector's calls over HTTP. |

Every type in them is in the [Reference](https://klef.ai/docs/connector-sdk/reference.md).

## What a Source Returns

A source is a connector whose manifest declares a `worker` object. Klef reads it like any other object, a page at a time, and its records are `SourceWorker`, the worker model in `Klef.Connectors.Model.Workers`. Whatever reads them relies on these rules, so a source keeps them on every read:

* Only people the source has officially hired are workers. Leave out a draft, an offer not yet accepted, and a contract awaiting a signature.
* Return a leaver, as terminated, for as long as the source holds them. Never leave a worker out to say they left.
* A full read that leaves out workers the source holds says so, with `PageNext.End` and `Partial` set.
* A lookup of named workers returns those the source holds and no others.
* Set `TerminatedAt` only when the source records the real moment the employment ended. A placeholder, such as midnight stamped on a contract that ran its course, is not one.

## The Lifecycle

**1. Write and test**

Scaffold a connector, write it, and test it against your test tenant. See [Getting Started](https://klef.ai/docs/connector-sdk/getting-started.md).

**2. Push a draft**

`klef connectors push` uploads the manifest as a draft revision. It shows up under **Connections > Custom connectors**.

**3. Run it with a relay**

Serve the connector with `klef connectors serve`. Make a runner key for it and start Klef's relay beside it with `klef relay`.

**4. Activate**

An Owner activates the revision, and plans use it from then on. An Owner can roll back by activating a revision that was active before.

> [!NOTE]
>
> Klef runs no tests of a connector your workspace writes. You own its behaviour and its tests, which you can run in your own CI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.