big docs
Integrations

Integration security

An API key for one of your tools is a password to that tool's account, and so is the sign-in token a tool gives big when you approve it. This page is what big does with them.

Tools connect in one of two ways, and big stores each differently:

  • A pasted API key: Calendly and Discord.
  • A sign-in token (OAuth) that the tool issues when you approve big's read-only access, for the few integrations big sets up for specific workspaces. There is no key to paste.

What big stores

When an admin connects an integration, big stores:

  • The credential itself, encrypted: the API key, or the sign-in tokens (a short-lived access token and the refresh token big uses to renew it). More on how below.
  • Which tool it's for, and the label the admin gave it.
  • The account it belongs to on the tool's side (its account id and its account name or label), as the tool reported it when big checked it.
  • For a pasted key only: the last 4 characters and a fingerprint, so you can tell keys apart without seeing them. A key shorter than 20 characters gets no last 4, since 4 characters would give away too much of it; the fingerprint alone identifies it. Sign-in tokens have neither: you never see them, and they change every time big renews them.
  • Dates: when it was connected, last checked, last used and last rotated, and the code of the last error, if any.

For most tools, apart from that account id and name, big doesn't copy any of the tool's data into big in this release; it calls the tool only to check the credential. The tools that feed client records are the exception. An integration your workspace has been set up for imports only what it is for into your client records: from a meeting tool, call transcripts, attendee names and emails, and AI summaries; from a file store, the text of the documents in the folders shared with big, kept for the whole workspace rather than on a client; from a calendar, the times of events your clients attend and which clients are on them. big keeps a raw copy of each transcript file and each file's text in private storage, so a failed import is retried from big's copy rather than from the tool. What happens to that data when you disconnect is under Disconnect deletes the credential.

How a pasted key is encrypted

Every pasted key is encrypted twice over, in layers:

  1. Each connection gets its own encryption key, generated fresh when you connect or rotate, and the API key is encrypted with it (AES-256-GCM).
  2. That per-connection key is then encrypted ("wrapped") by a master key held in Google Cloud KMS, on hardware security modules. The master key never leaves Google's hardware, and it rotates automatically every 90 days.

To wrap and unwrap it, Google Cloud KMS receives the per-connection key, together with internal ids (the workspace, the integration and the provider) as authenticated data that ties the wrapped key to this one connection. Google never receives your API key or its encrypted form, or any other content from your workspace, so Google Cloud alone can't decrypt a key, and neither can big's database alone. The same envelope protects sign-in refresh tokens, below. That makes Google Cloud a sub-processor for this one purpose; see Your data.

Each encrypted key is also bound to its workspace, its connection and its current version, so an encrypted key copied into another workspace, or restored from before a rotation, can't be decrypted.

Only big's production service can ask Google Cloud to unwrap a key, every unwrap is logged by Google, and no person at big, engineers included, holds the permission to unwrap one.

How sign-in tokens are encrypted

A sign-in gives big two tokens, and each is protected the way its job needs:

  • The refresh token, the long-lived one big uses to get new access, is encrypted the same way as a pasted key: with its own freshly generated encryption key (AES-256-GCM), which is wrapped by the master key held in Google Cloud KMS. Google Cloud KMS receives that per-token key and the internal ids that bind it to this one connection, never the refresh token or its encrypted form. Refresh tokens saved before October 2026 were encrypted with big's own token key; each moves to this form the next time big renews it. Until then big reads both forms.

  • The short-lived access token is encrypted with big's own token key (AES-256-GCM), the same one that protects your connected Instagram and Facebook accounts' access, so a call to the tool never waits on Google Cloud. That key lives only in big's production environment, never in the database.

  • Each token is bound to its place. The encryption ties every token to its integration, its workspace and the current version of the connection. A token copied to another integration or workspace, or into the wrong column, can't be decrypted.

  • Tokens live in their own table that big's application code can't read directly. Only a handful of database functions can reach it, each one checks the workspace, and big's code that reads the rest of your workspace can't see it at all.

  • While you are on the confirm screen, the tokens the tool just issued wait in the same kind of isolated table, bound to the tool, your workspace, the admin who started, and that one attempt. Cancelling or letting the screen expire deletes them.

  • A sign-in uses PKCE where the tool supports it. The one-time proof that the sign-in really started in big is encrypted the same way and deleted as soon as it is used.

Renewing. Access tokens are short-lived. big renews one with the refresh token shortly before it runs out, and stores the new pair in place of the old. Where a tool lets you approve its permissions one at a time, big also checks on every renewal that the access it needs is still there; access that has shrunk below that, or grown beyond what big asked for, is refused, and the integration moves to Reconnect needed. If the tool refuses to renew because big's access was revoked or the app removed, the integration moves to Reconnect needed and your admins are told; see Reconnect. A fault on big's side, such as a token that can't be decrypted, is never treated as a revoked grant: it doesn't delete anything or ask you to reconnect.

What you can see

Once saved, a credential is never shown again. The dashboard, the CLI, the API and both MCP servers show only:

  • For a pasted key, the last 4 characters, to recognise it at a glance. Keys shorter than 20 characters show none.
  • For a pasted key, a fingerprint, a short code computed from the key with a secret only big holds. The same key always gives the same fingerprint, so you can check "is this the key we rotated from?" without either key being shown. Because it needs big's secret, a fingerprint can't be used to test guessed or stolen keys.
  • For a tool you signed in to, the account big is connected to.

Nobody can read a key or token back after saving: not you, not your admins, and not big staff, whatever their access. There is no reveal button and no endpoint that returns one. When you need a key again, create a new one in the tool and rotate.

Writes are dashboard-only

Connecting, reconnecting, rotating, re-verifying and disconnecting work only in the dashboard, signed in as an admin.

  • API tokens and MCP can never read or change credentials. The integrations:read scope lets a token read the status fields above and nothing else. There is no integrations:write scope to grant. A token that tries one of the write actions is refused with a message saying it is dashboard-only, and the attempt is recorded in your workspace's audit history.
  • Why: a key typed into a CLI command or an agent's chat would land in shell history and chat transcripts, a leaked API token should never be enough to swap in someone else's credential or pull yours out, and signing in to a tool needs a browser anyway.
  • Signing in is bound to the admin who started it. big only accepts the tool's answer in the same browser, from the same signed-in admin, within 15 minutes, and saves nothing until that admin confirms. A link someone sends you can't attach their account to your workspace.

Every connect, reconnect, rotate, disconnect and failed check is recorded in the workspace's audit history, with a key's fingerprint and never the key or a token.

Calls to your tools

  • Only the tool's official API address. Each tool's address is fixed inside big No field you fill in can point big somewhere else, and big refuses to follow a redirect with your credential attached.
  • Sign-in tokens are renewed only at the tool's fixed address. big asks for a new access token only at the tool's own sign-in address, and never logs a token.
  • The tool's own error text is never shown or logged. When a check fails you get a short, fixed explanation from big, because a tool's error response can echo the credential back.
  • Credentials are kept out of logs. big scrubs anything shaped like a key from its logs, and never logs a key, a token, their encrypted form or the tool's response body.

Disconnect deletes the credential

Disconnecting deletes the stored key or tokens from big's live database immediately, together with a key's per-connection encryption key. What remains is the small audit record (tool, label, account, dates, a key's fingerprint), kept with your workspace's audit history and deleted with the workspace. Deleting the workspace deletes every integration's credential the same way.

Whether the tool forgets big too depends on the tool:

  • An API key: big can't revoke it. API keys are revoked where they were issued, so after you disconnect or rotate, delete the old key in the tool itself.
  • A tool you signed in to: revoked where the tool allows. Disconnect asks the tool to revoke big's access first, then deletes big's copy whether or not the tool answered. Where a tool has no revoke, remove big from your authorized apps in the tool.
  • A meeting integration: the imported calls are deleted. Disconnecting a meeting integration your workspace has been set up for also deletes every call big imported only from it, with its transcript, attendees and summary, big's raw copies of the transcript files, and any import of past calls still running. Recordings in the tool are never touched, and deleting a recording there does not delete big's copy.
  • A calendar integration: the update feeds are stopped first, then everything it imported is deleted. Disconnecting one your workspace has been set up for first tells the tool to stop sending big updates, using big's access while it still works, then asks the tool to revoke that access, and then deletes every calendar event big kept from it. Your calendar in the tool is never touched.
  • A file store: unlink the folder. big reads only the folders you link and share with it, and deletes a document's copy and text once it leaves a linked folder, or every document of a folder once you unlink it or it stops being shared with big big can't unshare itself, so also remove its address from the folder in the tool. See Google Drive. Your files in the tool are never touched.

Backups

big's database backups let us restore the database to a point in the past, for a limited window; contact us for its current length. A key or token you disconnected therefore still exists, encrypted, inside those backups until that window has passed, and only big's production service holds what it takes to decrypt it. After the window, it is gone from backups too.

Deleting big's copy doesn't stop a credential working at the tool. A key you pasted keeps working until you delete it in the tool. Revoke it at the tool to invalidate it.

Least privilege

The safest credential is one that can't do much:

  • Calendly: a personal access token. Calendly doesn't offer scoped tokens.
  • Discord: a bot token for a bot you create, with only the permissions big needs.
Integration security | itsjustbig