Connect an integration
Everything on this page happens in the dashboard and needs the admin role or higher. Members below admin see the same screens without the controls. There is no way to connect, reconnect, rotate or disconnect from the CLI, the API or an MCP tool.
Tools connect one of two ways:
- With an API key you create in the tool and paste into big: Calendly and Discord. See Connect with an API key.
- By signing in to the tool and approving big's read-only access (OAuth), with nothing to paste, for the few integrations big sets up for specific workspaces. See Connect by signing in.
Connect with an API key
- Open Connect in the sidebar, find the Integrations section and choose Browse catalog.
- Pick the tool you want to connect. Its screen says which kind of key to create and how to keep it as narrow as the tool allows. The per-tool pages have the same guidance: Calendly, Discord.
- Create the key in that tool, then paste it into big Give the integration a label you'll recognise later, for example "Sales Calendly".
- Save. big tests the key before it stores anything. It makes one read-only call to the tool with the key you pasted:
- If the tool accepts it, the key is encrypted and saved, and the integration shows as Connected with the account the key belongs to.
- If the tool rejects it, or the key is broader than big allows, nothing is saved and you see a short explanation. Fix the key and try again.
- If the tool is down or busy, nothing is saved and you can simply retry.
Once saved, the key is never shown again, to you or anyone else. The integration's page shows its last 4 characters and a short fingerprint so you can tell which key is in use. See Integration security.
Every connect, rotate or re-verify tests a key, and testing is limited in two ways: 10 attempts per minute per person, so a mistyped key can be retried straight away, just not in a tight loop; and a daily limit per workspace, across all its admins. Connecting and re-verifying share 30 key tests a day; once the workspace reaches it, they are refused until tomorrow. Rotating has its own 20 a day, so using up the connect and re-verify limit never stops you replacing a leaked key. Disconnecting tests nothing, so it is never limited.
A suspended workspace can't connect, rotate or re-verify an integration.
Connect by signing in
A tool you sign in to never takes a pasted key. big holds a sign-in token that the tool issues when you approve big, and big renews it on its own while the connection is healthy.
- Open Connect → Integrations → Browse catalog and pick the tool. Its screen lists exactly what big will be able to read.
- Choose the tool's Connect button. big sends you to the tool.
- Sign in there, choose the account, and approve big's read-only access.
- The tool sends you back to big's confirm screen. It shows:
- The account id as the main line, and the account's name smaller underneath. The account's owner chooses its name, so check the id.
- LIVE or TEST, for a tool that has test accounts, so you know which mode you approved.
- What it replaces, if the workspace already has an integration for that tool, with the old and the new account ids.
- Choose Connect to save it, or Cancel to throw it away. The confirm screen lasts 15 minutes.
Nothing is saved until you confirm, and only the admin who started the connection, signed in to big in the same browser, can confirm it. Before saving, big makes one read-only call with the new access to check it really belongs to the account the tool named.
Each account at a tool can be connected to one big workspace at a time. If another workspace already holds it, connecting is refused and that workspace's admins are told; if that workspace's access has stopped working, your confirm frees the account and connects it to you.
The connect button is hidden while big's connection to that tool isn't switched on. A suspended workspace, or one already at its plan's integration limit, is refused before you leave big, unless you are reconnecting a tool the workspace already has.
Reconnect
An integration you connected by signing in shows Reconnect needed when the tool stops accepting big's access, for example because big's app was uninstalled or removed from your account in the tool. Your admins get a notification and an email; see Notifications. big stops calling the tool until you reconnect.
Choose Reconnect on the integration's page and approve again. Reconnecting the same account brings the same integration back. Approving a different account replaces an integration that shows Reconnect needed, after you confirm, and doesn't take another slot on your plan. To swap a working integration for a different account, disconnect it first.
Rotate a key
Rotating applies only to tools you connect with an API key. An integration you signed in to has nothing to rotate; to replace its access, reconnect it.
Rotate when a key may have leaked, when someone who had access to it leaves, or on your own schedule.
- Create a new key in the tool.
- Open the integration in Connect → Integrations and choose Rotate.
- Paste the new key. big tests it exactly as it does on connect, and only replaces the old key once the new one works. If the test fails, the old key stays in place and keeps working.
- Delete the old key in the tool. big can't do this for you: an API key can only be revoked in the tool that issued it. Until you delete it there, the old key still works for anyone who has a copy.
The fingerprint changes when the key changes, so you can confirm the rotation took.
Re-verify
Re-verify re-runs the same read-only test against the key or access big already holds. Use it after fixing something in the tool, such as a key you re-enabled or a permission you added, to bring an integration in Error back to Connected without pasting the key again. An integration that shows Reconnect needed can't be re-verified; reconnect it instead.
big also watches for a dead key on its own: after 3 rejections in a row, it moves the integration to Error and stops calling the tool with it, rather than hammering the tool with a key that no longer works. Re-verify, or rotate to a new key, to bring it back.
Disconnect
Disconnect deletes the stored key or sign-in token from big's live database immediately. There is no undo; to use the tool again, connect it again.
A small record of the integration stays for your workspace's audit history: which tool it was, its label, the account, the dates, and a pasted key's fingerprint. It never includes the key, a token, or the key's last 4 characters.
Whether the tool itself forgets big depends on the tool:
- An API key: delete the key in the tool too. Disconnecting removes big's copy; it doesn't revoke the key where it was issued.
- A tool you signed in to: revoked where the tool allows. Disconnect asks the tool to revoke big's access before deleting big's copy. If the tool has no revoke, remove big from your authorized apps in the tool.
If you downgrade
Moving to a plan with a lower integration limit never disconnects anything:
- The integrations you already have keep working as before, and you can still re-verify, rotate and disconnect them.
- You can't connect a new one while you are over the new plan's limit. Connecting is refused with a message saying so.
- Disconnect the ones you don't need to get back under the limit, or upgrade.
Check status from your agent or the CLI
Anyone with a token carrying the integrations:read scope can see the same status the dashboard shows, including Reconnect needed (needs_reconnect), without a key ever being involved:
- CLI:
big integrations listandbig integrations status <id>. See the command reference. - MCP:
integration_statuson the remote server,big_integration_statuson the local one. See MCP. - API:
GET /api/integrations/status. See the API reference.
The same scope answers what your workspace can connect: big integrations catalog, integration_catalog and big_integration_catalog, or GET /api/integrations/availability, list each integration your workspace can see, whether it can be connected now or why not (already connected, not available yet, or your plan's limit reached), and how many of your plan's integrations are in use. For an admin, a connection made with your own app also shows its webhook address and the events to subscribe, as its page does.
All of them are read-only. Connecting, reconnecting, rotating and disconnecting are dashboard-only; credentials are never readable.