Skip to main content

​
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. 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.

​
Modes

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.

​
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 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.
  • Provider errors are sanitized. Raw provider messages stay ephemeral; what you receive is a fixed set of safe codes. See Errors & Recovery.

​
Availability

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

Connect an Account

Take a user through hosted OAuth and handle the return safely

Import & Export

Browse a provider, create a link, and follow its progress

Installations

Scope connectors per customer tenant in a multi-tenant application

Errors & Recovery

Reauthorization, access loss, throttling, and what to retry

Providers

Capability differences between Clio Manage and Google Drive

Vaults

Where imported documents land and become searchable

Events

Subscribe to run and connection lifecycle events instead of polling

Matters

Associate a link with a matter for case-level organization