> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Connectors Overview
> Move documents between provider folders and vaults
## The problem
The documents you need are already somewhere else. They sit in a Google Drive folder or a Clio matter—and they keep changing. Asking people to download them and re-upload them turns a living folder into a stale copy, and it puts you in the business of storing someone else's credentials.
## The solution
A connector links a **provider folder** to a **vault**. Case.dev moves the files, records what it moved, and can keep the two sides current as the provider folder changes.
Your application never handles provider credentials. It holds a connection id; the OAuth tokens stay inside the connectors service, encrypted under a per-connection key that is itself wrapped by AWS KMS.
## The object model
Four objects carry the whole system.
| Object | What it is |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Connection** | One authorized provider account. Created pending, becomes `healthy` after consent. Holds the tokens you never see. |
| **Link** | A standing relationship between one provider folder and one vault, in one direction. Identity is `(connection_id, direction, remote, vault_id)`. |
| **Run** | One execution of a link—a backfill, an incremental diff, or a full reconcile. |
| **Ledger entry** | One row per file, per link. Records the provider item, the vault object, the content version, and the outcome. |
The ledger is what makes transfers safe to repeat. Re-running a link diffs against the ledger instead of re-importing everything, so the "Re-import" button in your UI is just another `POST /connectors/v1/transfer`.
## Directions
A link moves files one way. Ask for `both` and you get a *pair* of one-way links, not a single bidirectional one.
| Direction | What moves |
| --------- | --------------------------------------------------------------------------------------------------------------- |
| `import` | Provider folder → vault |
| `export` | Vault → provider folder |
| `both` | Creates paired import and export links. Export defaults to a `CaseMark Output` subfolder under the import root. |
## Modes
| Mode | Behavior | How to get it |
| -------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `once` | Runs when you ask it to. `automation_status` is `manual_only`. | `POST /connectors/v1/transfer` |
| `synced` | Backfills now, then stays current. A sweeper re-runs synced links on a schedule. `automation_status` is `scheduled`. | `POST /connectors/v1/sync-link` |
Re-posting to `/transfer` never downgrades a synced link. To step a link back down, `PATCH /connectors/v1/links/{id}` with `mode: "once"`.
Synced links are kept current by polling on a roughly 15-minute cycle, not by provider push notifications. Treat it as "current within the hour," not real time.
## Policies
Each link carries a policy that governs what it moves and what happens to the far side.
| Setting | Values | Default behavior |
| ------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `deletes` | `mirror`, `preserve` | On imports, `mirror` removes the vault copy when the provider file disappears; `preserve` keeps it. Exports never delete on the provider side. |
| `collisions` | `version`, `overwrite`, `skip` | How an export resolves a name that already exists at the destination. |
| `filters.max_size_bytes` | integer | Files the provider reports as over the limit are skipped. A file that turns out larger mid-transfer fails with `connector_file_too_large`. |
| `filters.exclude_mime` | array of strings | MIME types to leave behind. |
## What transfers cost
Two separate things happen, and they bill separately:
* **The transfer itself** streams bytes from the provider into vault storage. Nothing buffers the whole file, so a large folder costs time and storage, not memory.
* **Downstream vault processing**—OCR, text extraction, chunking, and vectorization—is ordinary vault ingestion and is billed as such. See [Usage](/usage) for how it appears on your bill.
## Security model
* **Tokens never leave the service.** Your application holds a `connection_id`. Provider access and refresh tokens are envelope-encrypted—AES-256-GCM under a per-connection key wrapped by AWS KMS—and decrypted only for the provider call that needs them.
* **Browse references are opaque.** The `browse_ref` and `import_ref` values you get back are the only identifiers the API accepts. Never build one from a provider id supplied by a browser.
* **Connector calls are server-to-server.** Tenant context is derived from your API key and headers you set server-side. See [Installations](/connectors/installations).
* **Provider errors are sanitized.** Raw provider messages stay ephemeral; what you receive is a fixed set of safe codes. See [Errors & Recovery](/connectors/errors).
## Availability
| Provider | `provider` value | Availability |
| ------------ | ---------------- | ------------------- |
| Clio Manage | `clio` | Generally available |
| Google Drive | `gdrive` | Requires enablement |
To see what is live for your organization, read the `providers` array returned by `GET /connectors/v1/connections`. A provider gated for your organization returns `403 connector_scope_not_enabled` when you try to connect. Contact support to have one enabled.
## Next steps
Take a user through hosted OAuth and handle the return safely
Browse a provider, create a link, and follow its progress
Scope connectors per customer tenant in a multi-tenant application
Reauthorization, access loss, throttling, and what to retry
Capability differences between Clio Manage and Google Drive
## Related services
Where imported documents land and become searchable
Subscribe to run and connection lifecycle events instead of polling
Associate a link with a matter for case-level organization