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

# How connectors work

> Authorisation, syncing, refresh schedules and reconnecting - the mechanics.

A connector is a secure, read-only link between Vivacity and one of your tools. Here's what happens under the hood.

## Authorisation

When you connect a tool, you authorise access in one of two ways:

* **Sign-in (OAuth)** - you sign in to the tool and approve access. Vivacity never sees your password, and access can be revoked from either side.
* **API key** - for tools without sign-in flow, you paste a key. Vivacity stores it **encrypted** and uses it only for the access you granted.

Either way, setup requests **read-only** scopes.

## Syncing

<Steps>
  <Step title="First sync (baseline)">
    Vivacity reads your recent history to learn what's normal. This takes a few minutes for most accounts; large histories take longer.
  </Step>

  <Step title="Scheduled refresh">
    After that, Vivacity refreshes on a schedule so your briefings and answers stay current.
  </Step>

  <Step title="Manual sync">
    Need the latest right now? Use **Settings → Connectors → \[tool] → Sync now**.
  </Step>
</Steps>

## Connection states

| State                  | Meaning                                                                      |
| :--------------------- | :--------------------------------------------------------------------------- |
| **Connected**          | Working and syncing normally.                                                |
| **Syncing**            | A sync is in progress (first sync or refresh).                               |
| **Reconnect required** | Access expired or was revoked - open the connector and select **Reconnect**. |
| **Manual fallback**    | A direct connection isn't available yet; import the data manually for now.   |

## Reconnecting

Access can expire or be revoked by the tool (a password change, a removed permission). When that happens you'll see **Reconnect required** and a prompt. Reconnecting restores the link - **your history is kept**, nothing is lost.

## Rate limits & large accounts

Vivacity respects each tool's API limits and backs off politely, so a big first sync won't disrupt your tool. Very large histories simply take a little longer to fully load.

<Card title="Having trouble?" icon="wrench" href="/troubleshooting/connection-issues">
  Connection issues, expired access and sync delays - fixes here.
</Card>