Connectors

Application credentials

Bring your own OAuth app per Connector so employee authorizations run under your company's client

By default, an employee authorizing a Connector authorizes Merge’s OAuth app for it. That works, and for most Connectors you can leave it alone. Register your own OAuth app per Connector when you want one of three things:

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

When to add them

Most organizations start on Merge’s apps and switch when an employee asks why the consent screen says Merge, when they hit rate limits that are not theirs, or when a security review wants a tighter scope set. Some Connectors ship with no shared OAuth app at all and need your own from the start. The catalog marks those Action required, and they authenticate nobody until you add a credential.

Adding credentials is non-disruptive. Tokens employees already hold keep working until they refresh, then refresh against the new app.

Adding credentials in the dashboard

  1. Open Connectors and click the Connector you want to configure
  2. Go to the Application Credentials tab and click Add credential
  3. Copy the OAuth callback URL from the top of the dialog and register it with the provider before saving
  4. Pick the authentication method, then paste your client ID and client secret
  5. Set the scopes if the Connector supports scope customization, and save

Leave External ID blank unless you keep more than one OAuth app for the same Connector, which is the only case it distinguishes them.

The callback URL Workforce expects looks like this:

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

Copy the exact value from the dialog rather than this page, since an organization on its own Merge domain gets a callback on that domain. Register whatever the dialog shows in your OAuth app on the provider’s side. If the provider’s app config does not have it, the OAuth flow redirects to the wrong place and fails.

Deleting a credential later is not free: employees who authenticated through it have to reconnect that Connector.

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 employees, and on Google it blocks brand verification outright. Workforce 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 organization-owned domains would let authorization codes flow to any URL an organization 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. Merge 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 the Workforce console, paste the client ID and secret into each Google Connector you use. Drive, Gmail, and Calendar are configured separately.

An internal app scoped to your Workspace skips Google’s verification review. If you register the app as external, Google requires verification before general availability, so plan for that timeline.

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 employees 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, and pick single-tenant, since the app serves your own employees
  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, because Azure will not show it again.
  5. Under API permissions, add the Microsoft Graph permissions you need, such as Mail.Read and Files.ReadWrite, and grant admin consent for your tenant
  6. Copy the Application (client) ID and the secret into the Workforce console against each Microsoft Connector you use

Microsoft’s permission scopes are granular, so pick the smallest set that does what you need. The full Graph scope set runs to hundreds of permissions and 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, and offline_access cover most agent use cases.
  4. Save. Salesforce takes 10 minutes to provision the app, so wait that out before testing.
  5. Copy the Consumer Key (client ID) and Consumer Secret (client secret) into the Workforce console

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 set the OAuth scope set on the credential itself, in the same dialog. The editor shows the Connector’s default scopes so you can see what you are narrowing, one scope per line, with Reset to defaults to go back. Providers that separate them also get a User scopes and an Optional scopes field. Editing scopes requires the Manage credentials permission.

Use this to:

  • Drop write scopes if employees only need to read
  • Drop admin scopes if you only need user-level access
  • Add scopes the default does not include

Scope changes take effect on the next token refresh. Tokens employees already hold keep their old scopes until they expire and refresh.

When credentials change

Rotating your client secret at the provider requires updating it in the Workforce console. The old secret stops working immediately, and any token refresh after the swap fails until Workforce has the new one.

Plan rotation the same way as access-key rotation: update Workforce first, then rotate at the provider. The reverse leaves a window where every employee refresh fails.

Next

Bundle this Connector’s tools and decide who reaches them with Tool Packs.