Connecting OAuth Integrations

Why this page exists

Gmail, Google Calendar, Google Drive and Spotify hand out access tokens that expire in about an hour. If you paste one from an OAuth playground, the integration works for that hour and then goes quiet.

The fix is to give AI Partner a refresh token plus the OAuth app it belongs to. It then mints a fresh access token before each expiry, on its own, indefinitely — you do the setup once and never touch it again.

Every OAuth app on this page is free to create. The only services that cost money are the APIs themselves (see Costs at the bottom), and those are billed the same whether you use OAuth or a pasted token.

---

The short version

For Google and Spotify there's a one-click Connect button on the Integrations card:

1. Create your OAuth app (steps below) and paste its client ID and client secret into the card, then Save.
2. Click Connect. Authorize in the provider's own window. Done.

AI Partner captures the refresh token during that authorization and renews the access token for you from then on — you never paste a token, and it never expires. The manual refresh-token route further down still works if you prefer it or are scripting.

The Connect button appears once the client ID and secret are saved. Before that it will tell you to set the OAuth app up first. Register the redirect URI exactly as shown per provider — that's the one value that must match byte-for-byte.

---

Bring your own OAuth app

AI Partner does not ship a shared "Sign in with AI Partner" app. You register your own with each provider and paste the client ID and client secret once.

This is deliberate. A shared app would mean every install's data flows through credentials we control, and for Google it would require an annual third-party security assessment (CASA) costing $500–$4,500/year for the broader Gmail and Drive scopes. Bringing your own keeps every install free and keeps your data yours.

You need three values per provider:

Value	Where it goes
Client ID	Integrations card, e.g. GOOGLE_CLIENT_ID
Client secret	Integrations card, e.g. GOOGLE_CLIENT_SECRET
Refresh token	Integrations card, e.g. GOOGLE_CALENDAR_REFRESH_TOKEN

Once all three are saved, AI Partner refreshes the access token for you. You can leave the access-token field empty — it gets minted on first use.

---

Google — Gmail, Calendar, Drive

One OAuth app covers all three. Budget about 10 minutes.

1. 1
   Create a project

   Go to console.cloud.google.com and create a project. Free, and no billing account is required.

2. 2
   Enable the APIs

   APIs & Services → Library, then enable each one you want:

   • Gmail API
   • Google Calendar API
   • Google Drive API

   All three have free quotas.

3. 3
   Configure the consent screen

   Google Auth Platform → Branding. Choose user type:

   • Internal — only if you have Google Workspace. Simplest path: no verification, no user cap, no warning screen.
   • External — everyone else. Continue to the next steps.
4. 4
   Create the OAuth client

   Credentials → Create Credentials → OAuth client ID → Web application.

   Add this exact authorized redirect URI:

   https://<your-domain>/api/connectors/oauth/callback

   Google requires HTTPS for anything that isn't localhost. Copy the Client ID and Client secret it gives you.

5. 5
   Publish to production — do not skip this

   Set the publishing status to "In production".

   While the app is in Testing, Google expires every refresh token after 7 days. Your integration would silently stop working each week — the exact failure this whole setup exists to prevent.

   In production without verification you will see a "Google hasn't verified this app" screen on first connect (click Advanced → Go to (unsafe)), and you are capped at 100 connected accounts. Refresh tokens then last indefinitely.

6. 6
   Get a refresh token

   Go to the OAuth 2.0 Playground → gear icon → tick Use your own OAuth credentials → paste your client ID and secret.

   Select the scopes you need (see the table below), authorize, then click Exchange authorization code for tokens. Copy the refresh token.

7. 7
   Save it in AI Partner

   Open Integrations, find the Gmail / Calendar / Drive card, and fill in GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and the card's *_REFRESH_TOKEN field. Save.

   You're done — the connection now maintains itself.

Choose the narrowest scope that works

Scope choice decides whether you could ever be pushed into a paid security assessment. AI Partner defaults to the narrow set.

Scope	Tier	Annual assessment
gmail.send	Sensitive	None
gmail.readonly, gmail.modify	Restricted	Required if you ever seek verification
drive.file — files the app created or you picked	Non-sensitive	None
drive, drive.readonly — your whole Drive	Restricted	Required if you ever seek verification
calendar, calendar.events	Sensitive	None

Staying on gmail.send + drive.file + calendar keeps you permanently clear of it. Choose the broad Drive scope only if you genuinely need the agent to search files it did not create.

---

Slack

1. 1
   Create the app

   api.slack.com/apps → Create New App → From scratch.

2. 2
   Add scopes

   OAuth & Permissions → Bot Token Scopes. Typical set: chat:write, channels:read, channels:history, reactions:write, and search:read if you want message search.

3. 3
   Install and copy the token

   Install to Workspace, then copy the Bot User OAuth Token (starts xoxb-) into SLACK_BOT_TOKEN on the Slack card.

Slack bot tokens do not expire, so there is no refresh token to manage. Free, always.

---

GitHub

No OAuth app needed. Settings → Developer settings → Personal access tokens → Fine-grained tokens, scope it to the repositories you want, and paste into GITHUB_TOKEN.

Fine-grained tokens do expire on the date you choose — set a reminder, or pick a long expiry.

---

Notion

notion.so/my-integrations → New integration → copy the Internal Integration Secret into NOTION_API_KEY.

Notion integrations see nothing until you explicitly share pages with them. In Notion, open the page → ⋯ → Connections → your integration. Missing this step is the usual reason searches come back empty.

---

Atlassian — Jira and Confluence

id.atlassian.com/manage-profile/security/api-tokens → Create API token.

Fill in the card with your site URL (https://yourteam.atlassian.net), the account email, and the token. Free.

---

Microsoft — Outlook and Microsoft 365

1. 1
   Register the app

   entra.microsoft.com → App registrations → New registration. Free — no Azure subscription needed.

2. 2
   Add the redirect URI

   Platform Web, URI https://<your-domain>/api/connectors/oauth/callback.

3. 3
   Create a client secret

   Certificates & secrets → New client secret. Copy the value immediately — it is only shown once.

4. 4
   Grant Graph permissions

   API permissions → Microsoft Graph, e.g. Mail.Read, Mail.Send, Calendars.ReadWrite. Grant admin consent if your tenant requires it.

5. 5
   Save

   Paste into OUTLOOK_CLIENT_ID, OUTLOOK_CLIENT_SECRET, and OUTLOOK_TENANT_ID.

---

Spotify

developer.spotify.com/dashboard → Create app. Redirect URI https://<your-domain>/api/connectors/oauth/callback.

Copy the client ID and secret into SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET, then supply SPOTIFY_REFRESH_TOKEN so playback keeps working past the first hour.

Note: apps in development mode are limited to 25 listeners, and playback control needs the account to have Premium.

---

Everything else

These use a plain API key — paste it into the card and you're finished.

Service	Where to get the key
Stripe	Dashboard → Developers → API keys
HubSpot	Private app → Access token
Sentry	Settings → Auth Tokens (also set SENTRY_ORG)
AWS S3	IAM user → Access key + secret
Trello	trello.com/power-ups/admin
Apify	Console → Integrations
Twitter / X	developer.x.com — see cost note below

---

Watching a connector (event sources)

Some connectors can be watched — polled in the background so new activity reaches the agent on its own. Gmail is the first: once connected, AI Partner can watch the inbox and react to new mail (draft a reply, update a document, whatever the goal calls for).

Watching is opt-in and per connector — nothing polls until you turn it on, so a fresh install is silent. When you enable a watch:

• It polls on an interval (Gmail every ~90s), resuming from where it left off across restarts — no replayed or skipped messages.
• The credential refreshes itself (Phase 1), so a watch left running for weeks keeps working as long as the OAuth grant is valid.
• If the grant is ever revoked, the watch stops and the connector flips to needs reauthorization rather than hammering a dead grant. Reconnect to resume.

A connector must be connected before it can be watched — the watch has nothing to poll otherwise.

Verifying a connection

Each Integrations card has a Test button that makes a real call to the provider and reports what came back. Use it right after saving — a green "Connected" badge without a successful test only means the fields are filled in.

If a connection later shows needs reauthorization, the provider rejected the refresh token — usually because access was revoked, the password changed, or the Google app is still in "Testing" mode. Re-run the refresh-token step and save the new value.

---

Costs

OAuth app registration is free everywhere on this page. What can cost money:

Item	Cost
Google CASA assessment	$500–$4,500/year — only if you seek verification for restricted scopes. Not needed for personal or small-team use
Twitter / X API	Free tier discontinued February 2026. Now pay-per-use: ~$0.005 per post read, ~$0.015 per post created
Twilio (phone proxy)	~$1–2/month per number, plus per-minute and per-message charges
Apify, OpenAI, ElevenLabs	Usage-based; free allowances then metered

Slack, GitHub, Notion, Atlassian, Microsoft, Google, Trello, Stripe and HubSpot are all free to connect and free to use at normal volumes.

---

Troubleshooting

The connection worked for an hour, then stopped

You saved an access token but no refresh token. Add *_REFRESH_TOKEN plus the client ID and secret, and AI Partner will maintain it from then on.

It works for about a week, then stops

Your Google app is still in Testing. Google expires refresh tokens after 7 days in that mode. Set the publishing status to In production.

redirect_uri_mismatch

The URI registered with the provider must match byte for byte — including https://, the exact domain, and no trailing slash. Re-copy it from the provider console.

Google says the app isn't verified

Expected for an unverified app in production. Click Advanced → Go to (unsafe). Verification is only worth pursuing if you are distributing to more than 100 people.

Notion or Google Drive returns nothing

Both are share-scoped. Notion integrations need pages explicitly shared with them; the drive.file scope only sees files the app created or you picked. Either share the content or move to a broader scope.

I saved a key and the agent still says the tool doesn't exist

Saving now refreshes the agent's tool list immediately. If it persists, the credential failed to resolve — press Test on the card to see the provider's actual error.