> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/installation-and-setup/microsoft-copilot.md).

# Microsoft Copilot

Connect [Microsoft 365 Copilot](https://learn.microsoft.com/en-us/microsoft-365-copilot/) to BalkanID using the **BalkanID** Teams app.

**Recommended:** have your **Teams administrator** publish BalkanID for the organization (see [Organization deployment (recommended)](#organization-deployment-recommended)). End users then add the app from **Built for your org** and sign in with BalkanID — no MCP URL or API keys from **Bearer Auth Keys**. Each user signs in with OAuth so every tool call runs under their identity. No Copilot Studio, Power Platform solution import, or Custom Connector is required.

### Prerequisites

* Active **Microsoft 365 Copilot** or **Microsoft Teams** license for each user who will use the agent
* **Corporate work account** signed into Teams ([Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/)) — personal Microsoft accounts (@outlook.com, @gmail.com, and similar) are not supported
* BalkanID MCP enabled for your tenant (your customer success representative can confirm)

To **publish** BalkanID for your organization, IT also needs:

* [**Teams administrator**](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings) access — or permission to **Submit an app to your org** for admin review
* [BalkanID-teams-app.zip](https://mcp.balkanid.app/api/teams-app/download) — from the [MCP UI](https://mcp.balkanid.app) (**OAuth Connectors** → **Microsoft Copilot** → **Download app zip**) or the direct link
* [**Upload custom apps**](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings) enabled in your tenant if you will upload or sideload the package — see [Enable custom app upload (IT admin)](#enable-custom-app-upload-it-admin)

### Choose your path

| Path                          | When to use                                                     | Auth                |
| ----------------------------- | --------------------------------------------------------------- | ------------------- |
| **Org publish** (recommended) | Your Teams admin has published BalkanID for the organization    | OAuth               |
| **Submit for org approval**   | You are not an admin; request IT to approve the app package     | OAuth after publish |
| **Personal sideload**         | Pilot before org publish; app not yet in **Built for your org** | OAuth               |

### Organization deployment (recommended)

On Microsoft 365 Copilot and Teams, **Teams administrators** should publish the BalkanID agent package once for the organization. This keeps rollout, access, and audit aligned with company policy.

Submitting and publishing the package is a **one-time step per organization** (per app version). After publish, the app appears under [**Built for your org**](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings). End users follow [End users — after org publish](#end-users-after-org-publish) — they add the app and sign in with BalkanID; they do not upload the zip.

The agent discovers BalkanID MCP tools at runtime, so newly added or updated tools become available without another package upload. IT only needs to publish a new package for app-level changes such as permissions, instructions, branding, or authentication configuration — will be informed in advance by the BalkanID team.

#### Upload and publish the app package

Download [BalkanID-teams-app.zip](https://mcp.balkanid.app/api/teams-app/download), then upload and publish using **one** of the methods below.

**Teams Admin Center**

Use this path when you have **Teams administrator** access.

1. Sign in to the [Microsoft Teams Admin Center](https://admin.teams.microsoft.com).
2. Go to **Teams apps** → **Manage apps** → **Upload new app** (or **Upload**), and select the zip.
3. Open **BalkanID**, set publishing status to **Published**, and allow the app for the organization per your tenant policy.
4. Allow **2–4 hours** (sometimes longer) for the app to appear under **Built for your org**.

**Teams app — Submit to your organization**

**Or**, from the Teams client:

1. Open **Apps** → **Manage your apps** → **Upload an app** → **Submit an app to your org**, and select the zip.
2. Your tenant admin reviews and approves the submission in the Teams Admin Center — see [Submit and approve custom apps in your org](https://learn.microsoft.com/en-us/microsoftteams/submit-approve-custom-apps).
3. After approval and publish, allow **2–4 hours** (sometimes longer) for the app to appear under **Built for your org**.

{% hint style="warning" %}
If you are **not** a Teams administrator, use **Submit an app to your org** above or ask IT to publish via the Admin Center. See Enterprise Rollout.
{% endhint %}

#### Enable custom app upload (IT admin)

Skip if your tenant already allows custom app upload.

1. Sign in to the [Microsoft Teams Admin Center](https://admin.teams.microsoft.com).
2. Go to **Teams apps** → **Setup policies**.
3. Edit the active policy (for example **Global (Org-wide default)**).
4. Turn [**Upload custom apps**](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings) to **On**.
5. Click **Save**.

### End users — after org publish

Use this path when your administrator has **already published** BalkanID to your organization. The app appears under [**Built for your org**](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings) — you do **not** upload the zip yourself.

1. In Teams or Microsoft 365 Copilot, open **Apps** → **Built for your org**, add **BalkanID**, and open it.
2. Send a starter prompt, for example: “What is my BalkanID identity?” or “List all active integrations.”
3. When the agent asks you to connect, click **Sign in** in the chat (or open **Manage Connections** if a [connection manager](https://learn.microsoft.com/en-us/microsoftteams/platform/m365-apps/agent-connectors) prompt appears instead).
4. Sign in with BalkanID, select the correct **tenant**, and complete consent (Read and Write scopes).
5. Re-run your prompt.

{% hint style="info" %}
OAuth currently requires **both Read and Write** scopes. See Authentication and Permissions.
{% endhint %}

{% hint style="warning" %}
If the agent does not appear when you type `@` in Copilot, open **BalkanID** from the Teams app list or restart the Teams desktop client — M365 Copilot can take time to index a newly published app.
{% endhint %}

### Personal sideload (pilot)

Use this path only when BalkanID is **not** yet in **Built for your org** — for example during a pilot before IT publishes org-wide.

{% hint style="warning" %}
Personal sideload installs the agent for **you only** — it is not shared across the org. For production, use Organization deployment (recommended).
{% endhint %}

1. Open <https://mcp.balkanid.app>, sign in, and confirm the correct **tenant**.
2. In **OAuth Connectors**, select **Microsoft Copilot** and click **Download app zip**, or download [BalkanID-teams-app.zip](https://mcp.balkanid.app/api/teams-app/download) directly.
3. [Sideload the package](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings) for your account: **Apps** → **Manage your apps** → **Upload an app** → **Upload a custom app**, and select the zip.

   Your tenant must allow custom app upload. If upload is blocked, ask IT to enable it — see [Enable custom app upload (IT admin)](#enable-custom-app-upload-it-admin), or Submit for org approval instead.
4. Complete [End users — after org publish](#end-users-after-org-publish) from step 1 onward (sign in with BalkanID in the connection manager).

### Verify

Ask the agent: “Call whoami on BalkanID MCP.” You should see your email and tenant ID.

If connection or consent fails, retry OAuth from the connection manager, confirm you selected the correct BalkanID tenant, and start a **new chat**. For other issues, see Troubleshooting.

### Official documentation

Microsoft documentation for custom Teams apps, org publishing, and MCP agent connectors:

* [Submit and approve custom apps in your org](https://learn.microsoft.com/en-us/microsoftteams/submit-approve-custom-apps) — Microsoft Learn
* [Manage custom app policies and settings](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings) — Microsoft Learn
* [Register MCP servers as agent connectors](https://learn.microsoft.com/en-us/microsoftteams/platform/m365-apps/agent-connectors) — Microsoft Learn


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/balkanid-mcp/installation-and-setup/microsoft-copilot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.