Integrations

Every integration is optional and switches on when its environment variables are set (Configuration). In production, a missing key means that feature says it is not available; the sample data used in development is never shown.

Status at a glance#

Bank feeds#

The bank provider is chosen from the workspace's country:

Onboarding and Settings offer five countries: the United States, Canada, the United Kingdom, Germany (for the EU) and India. Bank connections are a Pro feature.

Plaid#

1. Create an app in the Plaid Dashboard with the Transactions product, and copy the client ID and secret for the environment you are using.
2. Set PLAID_CLIENT_ID, PLAID_SECRET and PLAID_ENV (sandbox, development or production). Production use needs Plaid's approval.
3. Connect bank opens Plaid Link in the browser. On success, Subsweep imports up to 12 months, and the hourly job then pulls the last 48 hours on every run.

Good to know: Plaid amounts are imported as positive values whether money went out or came in; the detection engine filters out most non-software rows. PLAID_REDIRECT_URI is passed to Plaid Link, but there is no page that resumes Link after an OAuth bank's redirect, so banks that require that flow may not complete.

TrueLayer#

Set TRUELAYER_CLIENT_ID, TRUELAYER_CLIENT_SECRET and, for live banks, TRUELAYER_ENV=production. Add <BETTER_AUTH_URL>/api/oauth/truelayer/callback as a redirect URI in the TrueLayer console.

The connection imports 12 months of transactions. TrueLayer access tokens are short-lived and Subsweep does not refresh them yet. Once the token expires, the hourly sync quietly brings in nothing while the source still looks connected. Treat it as a one-off import per connection for now: disconnect and reconnect to import newer transactions.

Salt Edge and Setu#

Both return pages check who comes back. When a connection is started, Subsweep stores a single-use state for that workspace, valid for 20 minutes. The return page attaches the bank only if that state is found and the person returning is signed in as an Owner or Editor of its workspace; otherwise they land on Sources with an error.

• Salt Edge: the connect session asks Salt Edge to return the connection ID. The return page checks with Salt Edge that the connection belongs to the customer created for this workspace, then stores the connection ID, which is what transaction fetches use.
• Setu Account Aggregator: India workspaces have no bank provider, so nothing in the interface starts a Setu consent, even with SETU_AA_ENABLED=true. Leave it unset. Its return page uses the consent ID stored with the state, and refuses a different ID or success=false.

Email receipts#

Both connections are read-only and a Pro feature. They scan when the mailbox is connected (and when someone presses scan again); the hourly job does not re-scan. See Email receipts for what is read.

Gmail#

1. In Google Cloud Console, enable the Gmail API and configure the OAuth consent screen with the https://www.googleapis.com/auth/gmail.readonly scope.
2. Create an OAuth client of type Web application with the redirect URI <BETTER_AUTH_URL>/api/oauth/gmail/callback.
3. Set GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET. If you leave them empty, the Google sign-in client is used, so that client then needs the Gmail redirect URI and scope as well.

gmail.readonly is a restricted scope: until Google has verified your app, connecting is limited (test users, or a capped number of people who see an unverified-app warning). See restricted scope verification.

Outlook#

1. Register an app in Microsoft Entra with the delegated permissions Mail.Read and offline_access.
2. Add the web redirect URI <BETTER_AUTH_URL>/api/oauth/outlook/callback and create a client secret.
3. Set MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET and, for a single-tenant app, MICROSOFT_TENANT.

Google sign-in#

Create a Google OAuth client (Web application) with the redirect URI <BETTER_AUTH_URL>/api/auth/callback/google, then set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. "Continue with Google" appears on the sign-in and sign-up pages once both are set. Sign-in only needs basic profile scopes, so it does not need the restricted-scope review that Gmail scanning does.

Slack#

1. Create a Slack app at api.slack.com/apps with the bot scopes chat:write, channels:read and incoming-webhook.
2. Add the redirect URL <BETTER_AUTH_URL>/api/oauth/slack/callback.
3. Set SLACK_CLIENT_ID and SLACK_CLIENT_SECRET.

Connect from Settings → Integrations and pick a channel during Slack's install screen. Alerts are only posted once the per-alert Slack switch is on, and that switch is not in the interface yet: see Slack for the workaround.

QuickBooks Online and Xero#

Settings → Integrations can connect either one over OAuth (redirect URIs <BETTER_AUTH_URL>/api/oauth/quickbooks/callback and <BETTER_AUTH_URL>/api/oauth/xero/callback), and the QuickBooks card has an Export now button that sends active subscriptions as bills.

Usage insights#

Routes exist to start OAuth with Google Workspace, Notion and Zoom (/api/oauth/usage/<provider>/start), but no screen links to them, and the callback only stores the authorisation code: no seat or activity data is fetched. Seat savings come from Offboarding instead.

Exchange rates#

With OPEN_EXCHANGE_RATES_APP_ID set, every hourly run fetches the latest USD rates from Open Exchange Rates for USD, CAD, GBP, EUR and INR, roughly 720 requests a month. Check that your Open Exchange Rates plan allows that. Without a key, fixed fallback rates are used.

Utilities#

Redirect URIs and webhooks#

Replace https://subs.example.com with your BETTER_AUTH_URL.