Administer

Application Credentials

Bring your own OAuth app per Connector for branding, rate limits, and scope control.

By default, Agent Handler uses Merge’s OAuth apps for each Connector. That covers testing and many embedded products. For production, you’ll often want your own OAuth app per Connector for three reasons:

  • Branding. Users see “Acme Inc. wants to access your Salesforce account,” not “Merge.”
  • Rate limits scoped to you. You compete with your own traffic, not Merge’s pooled traffic.
  • Scope control. You decide which OAuth scopes your app requests - often a smaller set than the default.

When to add them

Most teams start without Application Credentials and switch close to launch. Switch when customers ask why the consent screen says Merge, when you bump into rate limits that aren’t yours, or when a security review wants a tighter scope set. A few Connectors don’t ship with shared OAuth apps and require BYO from day one.

Adding credentials is non-disruptive - existing tokens keep working until they refresh, then refresh against the new app.

Adding credentials in the dashboard

  1. Open the Connector at Connectors, click the Connector you want to configure.
  2. Go to the Application Credentials tab.
  3. Click + Add Application Credentials.
  4. Paste your client ID and client secret. Specify the scopes if the Connector supports scope customization.
  5. Save.

The OAuth callback URL Agent Handler expects is always:

https://ah.merge.dev/oauth/callback

Register that URL in your OAuth app on the third party’s side. If the third party’s app config doesn’t have it, the OAuth flow will redirect to the wrong place and fail.

Example: Google (Workspace, Drive, Calendar, Gmail)

  1. Open the Google Cloud Console → APIs & Services → Credentials.
  2. Click Create credentials → OAuth client ID, type Web application.
  3. Add https://ah.merge.dev/oauth/callback to Authorized redirect URIs.
  4. Copy the client ID and client secret.
  5. Enable the APIs you need (Drive API, Calendar API, Gmail API) under APIs & Services → Library.
  6. Configure the OAuth consent screen - Google requires this even for internal apps. Set the app name (this is what shows on the consent screen), support email, and scopes.
  7. In Agent Handler, paste the client ID and secret into each Google Connector you’re using (Drive, Gmail, Calendar are configured separately).

For external apps (visible to users outside your Workspace), Google requires verification before going to general availability. Plan for the verification timeline if you’re shipping to consumers.

Example: Microsoft (Outlook, OneDrive, SharePoint, Teams)

  1. Open the Azure portal → Azure Active Directory → App registrations.
  2. Click New registration, give it a name, pick the right tenant configuration (single-tenant for internal, multi-tenant for B2B).
  3. Add https://ah.merge.dev/oauth/callback as the redirect URI under Web platform.
  4. Under Certificates & secrets, generate a client secret. Copy it now - Azure won’t show it again.
  5. Under API permissions, add the Microsoft Graph permissions you need (Mail.Read, Files.ReadWrite, etc.) and grant admin consent for your tenant.
  6. Copy the Application (client) ID and the secret into Agent Handler against each Microsoft Connector you’re using.

Microsoft’s permission scopes are granular - pick the smallest set that does what you need. The full Graph scope set runs to hundreds of permissions; you likely need a handful.

Example: Salesforce

  1. In Salesforce, go to Setup → App Manager → New Connected App.
  2. Enable OAuth settings. Add https://ah.merge.dev/oauth/callback to the callback URL list.
  3. Pick the OAuth scopes - api, refresh_token, offline_access cover most agent use cases.
  4. Save. Salesforce takes 10 minutes to provision the app - wait that out before testing.
  5. Copy the Consumer Key (client ID) and Consumer Secret (client secret) into Agent Handler.

Salesforce splits production from sandbox at the auth-URL level - production uses login.salesforce.com, sandbox uses test.salesforce.com. Make sure the Connector’s environment matches.

Scope customization

Most Connectors let you override the OAuth scope set after you’ve added Application Credentials. Open the Connector → Application Credentials → Scopes and edit the comma-separated scope list.

Use this to:

  • Drop write scopes if your agent only reads.
  • Drop admin scopes if you only need user-level access.
  • Add scopes the default doesn’t include.

Scope changes take effect on next-token-refresh. Existing tokens keep their old scopes until they expire and refresh.

When credentials change

Rotating your client secret in the third party requires updating it in Agent Handler - the old secret stops working immediately, and any token refresh after the swap will fail until Agent Handler has the new secret.

Plan rotation the same way as access-key rotation: update Agent Handler first, then rotate at the third party. The reverse leaves a window where refreshes fail.

Next

Authenticate dashboard members through your IdP with Single sign-on.