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. You can also narrow scopes without your own app, see Scope customization.

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.

There is one end-user-visible difference. Where a provider requires a limited-use disclosure, Link shows that notice before consent only when the user is authenticating against Merge’s default OAuth app. Once you supply your own app the notice stops appearing, because the disclosure covers Merge’s app rather than yours, and any equivalent disclosure for your app is yours to make on the provider’s consent screen.

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.

By default the OAuth callback URL Agent Handler expects is:

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.

Using a callback URL on your own domain

On providers that display the callback’s domain during consent, the default callback puts merge.dev in front of your users, and on Google it blocks brand verification outright. Agent Handler can send both legs of the OAuth flow to a callback on a domain you own instead, set per Application Credential, so one Connector uses your domain while every other Connector keeps the default.

This is narrower than it sounds, so check that it applies to you before asking for it. It works only alongside your own OAuth app: pointing Merge’s shared apps at customer-owned domains would let authorization codes flow to any URL a customer names, so Merge does not offer it there. On most providers the consent screen is branded from the client ID you supply, which registering your own OAuth app already fixes without touching the callback. Google is the case this exists for.

You host the callback yourself. The endpoint on your domain forwards the code and state query parameters verbatim to https://ah.merge.dev/oauth/callback, which is where the flow still completes. A 302 that preserves both parameters is enough. Agent Handler performs the token exchange, so no token or client secret passes through your endpoint.

To set it up:

  1. Stand up the forwarding endpoint on your domain, for example https://auth.acme.com/merge/callback
  2. Add that URL to your OAuth app on the provider’s side, and list your domain under the provider’s authorized domains (Authorized domains in the Google Cloud Console)
  3. Contact Merge with the Connector and the URL. Merge sets the override on that Application Credential, since it is not editable in the dashboard.

The override is scoped to one Application Credential, meaning a single organization, Connector, and auth option. https://ah.merge.dev/oauth/callback keeps working everywhere else, and for that same Connector again if the override is removed.

Early access
Merge configures this by hand, and it has not been verified end to end against a live provider app yet. Test one Connector before you roll it out across the rest, and tell your Merge contact what you find.

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.

Google is also the clearest case for a callback on your own domain. Until a brand is verified, Google’s consent screen shows the registrable domain of the redirect URI, so with the default callback your users read “merge.dev wants access to your Google Account” even though the app is named after you. Verification does not fix it on its own either, because Google asks you to prove ownership in Search Console of every authorized domain, and you cannot prove ownership of merge.dev. If you are registering your own Google app, set up a callback on your own domain at the same time.

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, and you do not need your own OAuth app to do it. The override applies to Merge’s default credential as well as one you supply, so a team that only wants to drop write scopes can stop here.

Override scopes from either the Connectors list, using the Override action and choosing Override OAuth scopes, or from the Connector’s Application Credentials → Scopes tab. Either route edits the same comma-separated scope list, and the dialog shows the Connector’s default scopes so you can see what you are narrowing. Editing scopes requires the Manage credentials permission.

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.

Reading credentials back

Reading an Application Credential over the API never returns a secret. Client secrets and tokens are write-only, and stay masked however you fetch them.

Connector configuration that isn’t secret does come back, such as an instance URL or a subdomain, so a settings page you build on the endpoint can show which values are already configured rather than masking the whole form.

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.