Overview

To allow your customers to link Microsoft teams accounts with Merge, you will need to set up a Microsoft Developer App and enter your applications credentials in Merge. This is a 5 step process:

Step 1: Sign up for the Microsoft Developer Program (prerequisite)

1. If you do not have a Microsoft developer account, sign up for one here.

2. Complete the form using the instructions given below.

   1. Fill out the first page with information about your organization, including the Region you are located in, your organization's name, and your language preference.

   2. When prompted for your "primary focus as a developer", select "Custom solutions for my own customers".

      

   3. When prompted "what areas of Microsoft 365 development are you interested in?", be sure to select "Microsoft Teams" and "Microsoft Graph".

   If you plan on offering connectors for other Microsoft tools, like Outlook, you can check those boxes as well.

Step 2: Create an OAuth application

1. Navigate to the app registrations page.

2. Click "New Registration"

   

3. Complete the form following the steps below

   1. Name: Fill the "name" field with your organization's name. This is the name that will appear in the OAuth flow during authentication.

   2. Supported account types: Options 2 or 3 are both valid. Merge recommends option 3 if you plan to offer Agent Handler to individual users who will be connecting using their personal email address.

      1. Accounts in any organizational directory

      2. Accounts in any organizational directory and personal Microsoft accounts

   3. Redirect URI: Web

   4. Redirect URI: https://ah.merge.dev/oauth/callback

4. Click "Register" to save your app.

Step 3: Saving web application values in Merge

1. Clicking Register will take you to a new page with your OAuth app credentials.

2. Paste the information below into your Agent Handler Instance.

   1. Client Id - The Application ID shown in the screenshot above

   2. Client Secret - The "client credentials" link

      1. Click the link, and hit "New client secret"

      2. Enter a description (eg "Merge Agent Handler")

      3. Leave the "expires" setting as the default value of "180 days (6 months)"

3. Input the credentials into Merge Agent Handler via the Connectors page, and clicking the "+ Add connector" button

Step 4: Tenant support

Follow step A or B depending on your Agent Handler product strategy.

A: Single tenant

If you plan on only connecting to a single Microsoft Teams instance (ie your Agents are going to be used by internal users only), you are developing a "Single-tenant" OAuth app.

Navigate to the "Authentication" page in Microsoft, and select the "Accounts in this organizational directory only (MSFT only - Single tenant)" option.

B: Multi-tenant

If you plan on only connecting to multiple Microsoft Teams instances (ie your Agents are going to be used by multiple customers, each with their own teams instance), you are developing a "Multi-tenant" OAuth app.

Navigate to the "Authentication" page in Microsoft, and select the "Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)" option.

Additionally, copy your OAuth app tenant ID from the app overview page. You will need this during authentication.

Step 5: Permissions

Microsoft OAuth apps require that all scopes your agent will request are allowed by the app. To configure permissions for your app, navigate to "API Permissions"

Required permissions

There are some permissions that are required for any tool call.

Permissions by tool

You will need different permissions based on the tools you plan to enable for your agents. The following table breaks down the permission required for each tool call.