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

# Connectors

> Ingest AI activity from external systems into Velatir.

Velatir connectors pull AI activity from external systems into your Velatir Activity surface. Each connector is an inbound source — Claude, OpenAI ChatGPT Enterprise, Microsoft 365 Copilot, and others — that runs on a periodic sync against the vendor's API, maps the vendor's shape into Velatir's canonical event + trace models, and writes through the same Activity / Traces / Inventory / Posture surfaces as the browser extension and desktop agent.

<CardGroup cols={2}>
  <Card title="Microsoft 365 Copilot" icon="microsoft" href="/connectors/microsoft-365-copilot">
    Pull Copilot activity (audit + conversation content) over Microsoft Graph with
    admin-consent to a dedicated Velatir Entra app.
  </Card>
</CardGroup>

## How connectors work

Every connector is an implementation of a single `IVendorConnector` contract with five optional methods. The sync worker dispatches one job per connector per pass; each method either returns data or returns null when unsupported.

| Method                   | When it runs                                                      | What it produces               |
| ------------------------ | ----------------------------------------------------------------- | ------------------------------ |
| `TestAsync`              | When you click **Test** in the wizard                             | Validates the credential       |
| `PullEventsAsync`        | Every sync pass                                                   | `ServiceEvent` rows (Activity) |
| `PullContentAsync`       | After each event page, for surfaced resource ids                  | `Trace` rows (per-message)     |
| `PullContentStreamAsync` | After each event page, for vendors that deliver content in-stream | `Trace` rows                   |
| `PullSettingsAsync`      | Daily posture pass (and on-connect)                               | `ConnectorSettingsSnapshot`    |

## Auth

Two flavours:

* **API key** (Claude, OpenAI ChatGPT Enterprise). The customer's compliance access key is stored write-only in Scaleway Secret Manager; only a reference id + masked suffix stay on the connector row.
* **OAuth / admin consent** (Microsoft 365 Copilot). No customer-supplied secret. The customer grants admin consent to a dedicated Velatir Entra app, the connector mints app-only client-credentials tokens at sync time, and the tenant id rides in `ConfigJson.tenantId`.

## When to use a connector

If your organisation has already deployed browser extension or desktop-agent coverage on the systems your people use, you may not need a connector — the extension is faster and richer. Connectors shine when:

* You want coverage on a system where the extension isn't installed (managed devices, kiosks, bring-your-own)
* You need a vendor-attested record of activity (e.g. audit-grade ingestion) rather than a self-reported trace
* You're standardising on a specific vendor and want a single pane of glass across endpoints