> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Microsoft 365 clients

> Connect Automagically to your Microsoft 365 clients: connect Partner Center, set up your GDAP app, authorize GDAP clients with no client action, and connect direct clients with admin consent.

> [!NOTE]
>
> Automagically is currently in a **closed beta**.

Automagically runs IT automation in your clients' Microsoft 365 tenants. This page covers how it connects to each tenant, what you set up once as an admin, what each technician does, and how to fix the common problems.

## What you get

* **GDAP clients connected with no client action.** Automagically is authorized in each GDAP client through Partner Center. The client's admin doesn't click anything.
* **Per-technician access.** In GDAP clients, Automagically acts with each technician's own GDAP roles, and operations show under that technician in the client's Microsoft audit logs.
* **Direct clients too.** Clients you don't manage through GDAP connect with a one-time admin consent link.
* **Your own tenant and a test tenant.** Connect your MSP tenant for internal automation, and a staging tenant to test runbooks safely.

## How the connection works (read this first)

GDAP clients are connected in two layers, and you need both:

1. **The workspace connection (admin, once).** Connect Partner Center and set up your GDAP app. This tells Automagically which clients you manage and lets it authorize itself in them.
2. **Each technician's sign-in (every technician, once each).** Every technician who runs automations in GDAP clients connects their own Microsoft account. Automagically then acts with that technician's GDAP roles: a technician can never do more through Automagically than their GDAP access allows.

If automations work for one technician but not another on the same GDAP client, it's almost always layer 2.

> [!TIP]
>
> **Application vs delegated permissions.** Application permissions give the app its own standing access to a tenant, so operations run as "the app". Delegated permissions let the app act on behalf of a signed-in person, limited to their roles and recorded under their identity. Direct clients, your MSP tenant and your staging tenant use application permissions. GDAP clients use delegated permissions.

| Connection | Who sets it up | Least privilege required | Needed for |
| - | - | - | - |
| Partner Center | Admin, once | Admin Agent (Partner Center) and Application Administrator (Entra ID), in your own partner tenant | GDAP clients |
| GDAP app | Admin, once | Cloud Application Administrator or higher, in your own tenant | GDAP clients |
| GDAP client authorization | Automatic | Cloud Application Administrator, Application Administrator or Global Administrator in an active GDAP relationship with the client | Each GDAP client |
| Your Microsoft sign-in | Each technician, once | Member of the GDAP security groups that hold the required roles | Running automations in GDAP clients |
| Admin consent | The client's Microsoft admin | Application Administrator in the client tenant | Each direct client |
| MSP tenant and staging | Admin | Application Administrator in the target tenant | Internal automation and testing |

## Connect GDAP clients

### Step 1: Connect Partner Center (admin)

Connecting Partner Center lets Automagically discover the clients you manage through GDAP and authorize itself in them.

You need an account that is an **Admin Agent** in Partner Center and holds **Application Administrator** (or higher) in Entra ID. You can remove Application Administrator from the account once the connection is made. It's only needed again if you reconnect.

> [!WARNING]
>
> Use a dedicated service account where possible. The connection is tied to the account that made it. If that account's password changes, its MFA is reset or it's disabled, Partner Center shows **Reconnect needed** until someone signs in again.

The account must belong to your own partner tenant:

* It must be a **member** of the tenant, not a guest.
* It doesn't have to be your Thread login. A separate privileged admin account works.
* Your Thread login's email domain must be a verified domain in that tenant, and your Thread email must exist as a user there.
* If your Partner Center is in a different tenant from your email domain, contact Thread support before you connect.

**1. Open the Microsoft 365 connect flow**

In Automagically, go to **Integrations**. On the Microsoft 365 card, open **Connect clients**, then click **Connect with GDAP**. (During onboarding, the same option is on the clients step.)

**2. Connect Partner Center**

Click **Connect Partner Center** and sign in with your partner tenant account. Complete MFA: Microsoft requires it for Partner Center.

**3. Approve the permissions**

Approve the permissions listed below.

Automagically checks the account belongs to your partner tenant. Partner Center then appears on the Microsoft 365 card as **Connected**, and the wizard lists your GDAP tenants.

| Permission | Why Automagically needs it |
| - | - |
| `DelegatedAdminRelationship.Read.All` | Reads your GDAP relationships, to discover your clients and check their roles. |
| `Partner Center user_impersonation` | Authorizes your GDAP app in your clients through Partner Center. |
| `User.Read`, `User.ReadWrite.All` | Confirm which tenant the signing-in account belongs to. |
| `openid`, `profile`, `email`, `offline_access` | Identify the signed-in admin and keep the connection alive. |

> **Why does Partner Center need User.ReadWrite.All?**
>
> When you connect, Automagically checks that the account belongs to your own partner tenant and that your Thread email is a user there. That protects you from someone connecting your Partner Center to a different Thread workspace. Microsoft accepts this permission for the user lookup, and the Automagically app already holds it, so the connection asks for nothing new. Automagically only reads with it during the connect.

### Step 2: Set up your GDAP app (admin)

Microsoft only lets a partner authorize an app in its customers through Partner Center when the partner owns the app. So Automagically creates a copy of its app in your own tenant, owned by you, called **Automagically - M365 GDAP**. All GDAP work runs as this app.

> [!TIP]
>
> **Two apps, one product.** *Automagically - M365* (Thread's app) is used for direct clients and your MSP and staging tenants. *Automagically - M365 GDAP* (your copy, with the same permissions) is used for your GDAP clients. You'll see both in your Entra tenant.

You need **Cloud Application Administrator** or higher (for example Application Administrator or Global Administrator) in your own tenant. Partner Center must be connected first.

**1. Start the GDAP app setup**

On the Microsoft 365 card, click **Set up** on the **GDAP app** row.

**2. Approve two temporary permissions**

Sign in to the same tenant you connected Partner Center with, and approve two temporary permissions for Thread's app: `Application.ReadWrite.All` (to create your app) and `DelegatedPermissionGrant.ReadWrite.All` (to remove both permissions again afterwards).

**3. Automagically creates your app**

Automagically creates **Automagically - M365 GDAP** with its own certificate, and removes the two temporary permissions from Thread's app straight away.

**4. Grant consent for the new app**

These are the same Microsoft Graph, Exchange and SharePoint permissions the Automagically app already uses. Until you do, the row shows **Consent pending**.

**5. Connect Partner Center again, as the new app**

Until you do, the row shows **Partner Center pending**. The row then shows **Active**.

The flow takes about a minute. A sign-in from any tenant other than your Partner Center tenant is refused.

When the app becomes active:

* Every GDAP client you've already mapped is authorized automatically.
* Each technician reconnects **Your Microsoft sign-in** once, because their earlier sign-in was made with Thread's app.
* Direct clients aren't affected.

The app's certificate lasts 2 years. The row shows **Expires soon** when it's due. Contact Thread support to renew it.

### Step 3: Map and authorize your GDAP clients (admin)

On the Microsoft 365 clients page, click **Connect with GDAP** and map each client to its Microsoft tenant. Automagically then authorizes your GDAP app in that client through Partner Center, applies the app's permissions and checks the client's GDAP roles. The client's admin doesn't do anything.

Authorization also runs:

* For every mapped client, when your GDAP app becomes active.
* When you click **Authorize** on a client.
* For all clients, when you click **Authorize all GDAP clients**. Tick **Also update clients authorized with an older permission list** to bring older authorizations up to date.

Each client needs an active GDAP relationship that grants **Cloud Application Administrator**, **Application Administrator** or **Global Administrator** to a security group your Partner Center account is in.

Each GDAP client shows one of these statuses in the **Partner Center** column of the clients table.

| Status | What it means |
| - | - |
| Authorizing | Authorization is running. |
| Authorized | The app is authorized with its current permissions. |
| Permissions out of date | The app is authorized with an older permission list. Run **Authorize all GDAP clients** with the update option ticked. |
| Temporary failure | Partner Center was busy or unavailable. Automagically retries for up to about 90 minutes. |
| Update failed | Updating an earlier authorization failed. The earlier one still works. The client shows the reason and the fix. |
| Failed | Authorization couldn't complete. The client shows the reason and the fix. |
| Not authorized | Authorization hasn't run yet. |

A client you **Disconnect** stays disconnected until you click **Authorize** on it. Discovering, mapping again or **Authorize all GDAP clients** won't reconnect it.

### Step 4: Each technician connects their Microsoft account

Every technician who runs automations in GDAP clients signs in once:

**1. Open Your Microsoft sign-in**

In Automagically, go to **Integrations** and find **Your Microsoft sign-in** on the Microsoft 365 card. The row appears once your workspace has a GDAP client.

**2. Connect your Microsoft account**

Click **Connect** and sign in with your own Microsoft work account: the one your Thread login uses, which holds your GDAP access.

**3. Confirm the row shows Connected**

The row shows **Connected**.

When you run an automation in a GDAP client, Automagically asks Microsoft for access to that client on your behalf, and Microsoft only grants what your GDAP roles allow there.

You stay connected from then on: Automagically refreshes idle Partner Center and technician sign-ins daily. If Microsoft stops accepting a sign-in, the row shows **Reconnect needed** and why.

#### Required GDAP roles

Automagically checks each GDAP client's relationships for these roles. A client connects as long as it has at least one, and lists any that are missing. Automations that need a missing role fail in that client. A client with none of them shows **Failed**.

| Role | Why it's needed |
| - | - |
| Application Administrator | App registration and consent management. |
| Authentication Policy Administrator | Authentication methods and MFA policies. |
| Cloud Device Administrator | Device management in Entra ID. |
| Exchange Administrator | Mailbox and mail flow management. |
| Global Reader | Read-only access across all services for discovery. |
| Intune Administrator | Endpoint and device policy management. |
| Privileged Authentication Administrator | Reset passwords and manage authentication for all users. |
| Privileged Role Administrator | Manage role assignments in Entra ID. |
| Security Administrator | Security policies and incident management. |
| SharePoint Administrator | SharePoint Online and OneDrive management. |
| Teams Administrator | Microsoft Teams configuration and policies. |
| User Administrator | User lifecycle: creation, licensing, group membership. |

Technicians must be members of the GDAP security groups these roles are assigned to in Partner Center.

> [!NOTE]
>
> **When no technician sign-in is available.** If Automagically can't use a technician's sign-in in a GDAP client, for example because it needs reconnecting, it falls back to application permissions only when the client's own admin has also consented the Automagically app directly. Those operations use that consent rather than GDAP roles and aren't recorded under a technician. Without that consent, the operation can't run until the technician reconnects.

## Connect direct clients

For clients you don't manage through GDAP, the client's Microsoft admin approves the Automagically app once. They don't need a Thread account.

**1. Find the client**

Open **Microsoft 365 clients** and find the client.

**2. Share the consent link**

Click **Copy link** and send it to the client's Microsoft admin (Application Administrator or higher), or click **Connect** to complete it yourself if you're an admin in their tenant.

**3. Admin approves the permissions**

The admin signs in and approves the permissions. The client then shows as connected.

> [!WARNING]
>
> **Sign in as the right admin.** Microsoft reuses whichever account your browser is already signed in to. If the consent comes back with your staging tenant, or a tenant another of your clients already uses, Automagically refuses it and saves nothing. Open the link in a private window, or send it to the client's admin.

The consent covers everything Automagically can automate in that one tenant: users and groups, sign-in and MFA, mail and Exchange, Teams, SharePoint and OneDrive, Intune devices and security policy. See [What the permissions are for](#what-the-permissions-are-for) below for the full list.

**DAP clients.** Partner Center also discovers clients you still manage through DAP, the older Delegated Admin Privileges. They connect with admin consent, like direct clients. Microsoft recommends moving them to GDAP.

## What the permissions are for

When a client's admin approves **Automagically - M365**, or you grant consent for **Automagically - M365 GDAP**, Microsoft shows a long list of permissions. It's long for three reasons.

1. **Most permissions appear twice.** The first half of the list is application permissions, worded like "...in all mailboxes" or "...all site collections". Automagically uses them for direct clients, your MSP tenant and your staging tenant. The second half is the matching delegated permissions, worded like "...user mail" or "Send mail as a user". Automagically uses them in GDAP clients, where it acts as the signed-in technician and can't do more than that technician's GDAP roles allow.
2. **One consent covers every runbook.** Consent is given once per tenant, not once per runbook, so the app asks for what every supported runbook might need. What actually runs is still controlled by runbook approval, Automagically roles, and (in GDAP clients) each technician's GDAP roles.
3. **Some areas use more than one Microsoft API.** "Have full control of all site collections" appears four times because it's granted in both Microsoft Graph and SharePoint, each as an application and a delegated permission. The "Manage Exchange..." permissions come from Exchange Online, because tasks like mail forwarding, shared mailboxes and mailbox permissions aren't available in Microsoft Graph.

| Area | Permissions you'll see | Why Automagically needs them |
| - | - | - |
| Partner and GDAP | Read Delegated Admin relationships with customers | Discover your GDAP clients and check which roles each relationship grants. |
| Tenant basics | Read organization information, Sign in and read user profile, Read all usage reports, Read all audit log data | Identify the tenant, read licence and usage data, and check what a run changed. |
| Users and groups | Read and write directory data, Read and write all users' full profiles, Read and write all groups | Onboarding and offboarding, licensing and group membership. |
| Admin roles | Read and write all directory RBAC settings | Runbooks that change role assignments. During setup, Automagically also uses it to give its own app the Exchange Administrator role, which Microsoft requires before an app can run Exchange tasks. |
| Sign-in and MFA | Read and write all password profiles and reset user passwords, Read and write all users' authentication methods, Read all users' password authentication methods | Password resets, MFA registration and reset, and recovering a user who lost their device. |
| Security | Read and write your organization's conditional access policies, Read your organization's policies, Read and write all risky user information, Read all security alerts, Read your organization's security events | Conditional Access changes, confirming or dismissing risky users, and triaging security alerts. |
| Mail and calendar | Read and write mail in all mailboxes, Send mail as any user, Read and write all user mailbox settings, Read and write calendars in all mailboxes | Out-of-office replies, delegate access, mail cleanup and calendar permissions. |
| Exchange | Manage Exchange As Application, Manage Exchange as application v2, Manage Exchange configuration | Exchange tasks that Microsoft Graph can't do: mail forwarding, shared mailboxes, mailbox permissions and mail flow rules. |
| Teams | Create channels, Read the members of all channels, Add and remove members from all channels | Team and channel setup, and membership changes during onboarding and offboarding. |
| SharePoint and OneDrive | Have full control of all site collections, Read items in all site collections, Read and write files in all site collections | Site permissions, external sharing, and handing over a leaver's OneDrive. |
| Intune | Read and write Microsoft Intune devices | Device lookups, sync, retire and wipe. |

## Connect your staging tenant

**Staging tenant:** on the Microsoft 365 card, click **Connect staging tenant** to link a test tenant and try runbooks before they reach real clients. You can finish setup with only a staging tenant and connect clients later.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Partner Center connect says the account is a guest | You signed in with a guest account in your partner tenant | Sign in with an account that's a **member** of your own partner tenant. |
| Partner Center connect says your tenant hasn't verified your Thread email's domain | You signed in to a different tenant, or your Partner Center is in a separate tenant from your email domain | Sign in to the tenant that owns your email domain with its Admin Agent account. If your Partner Center really is in a separate tenant, contact Thread support. |
| Partner Center or **Your Microsoft sign-in** shows **Reconnect needed** | Microsoft ended the sign-in (for example after a password change), now requires MFA, or a Conditional Access policy blocked it | Click **Reconnect**, sign in again and complete MFA. |
| A GDAP client fails with "no role that can authorize the app" | No active GDAP relationship grants Cloud Application Administrator, Application Administrator or Global Administrator | Add one of those roles to an active GDAP relationship and click **Authorize**, or connect the client directly. |
| A GDAP client fails because of Conditional Access | The client's Conditional Access policies block your partner sign-ins | Ask the client's admin to exclude your partner sign-ins from the policy. |
| A GDAP client lists missing roles | Its GDAP relationship doesn't grant every required role | Automations that need those roles fail in that client. Add the roles to a GDAP relationship. |
| Direct consent says the tenant is already connected to another client | Your browser was signed in as another admin, so Microsoft returned the wrong tenant | Open the link in a private window and sign in as the client's admin. If the client really shares that tenant with another client, first add a contact on one of the tenant's email domains to the client. |
| Automations work for one technician but not another | That technician hasn't connected **Your Microsoft sign-in**, or isn't in the right GDAP security groups | Have them connect their Microsoft account (Step 4) and check their GDAP group membership. |

## FAQ

> **Do my clients need to do anything?**
>
> GDAP clients: no, Automagically is authorized through Partner Center. Direct clients: their Microsoft admin approves a consent link once. Neither needs a Thread account.

> **Can I connect Partner Center with a separate admin account?**
>
> Yes, as long as it's a member (not a guest) of your own partner tenant and your Thread email is a user in that tenant.

> **What happens when a technician leaves?**
>
> Their sign-in stops working once their Microsoft account is disabled. Nothing shared is affected, and other technicians carry on with their own accounts.

> **Can I have both GDAP and direct clients?**
>
> Yes. To move a client that's working on a direct connection to GDAP, map it over GDAP. Automagically asks you to confirm first, because it changes how that client connects.

> **What is CPV, and why doesn't Automagically need it?**
>
> Control Panel Vendor (CPV) is a Microsoft program that lets a vendor's app be authorized in partners' customers. Automagically creates a copy of its app that you own instead, and Microsoft lets partners authorize their own apps in their customers, so no CPV enrollment is needed.

> **Is authorization per client or global?**
>
> Per client. Each tenant is authorized independently, so you control which tenants Automagically can access.


## Related topics

- [Install the Teams Companion App](https://docs.getthread.com/companion-apps/install-the-teams-companion-app.md)
- [Thread MCP Server: Developer Guide](https://docs.getthread.com/super-magic/thread-mcp-server-developer-guide.md)
- [Automate PSA Scheduling with Microsoft Bookings](https://docs.getthread.com/integrations/microsoft-bookings-integration-for-psa-scheduling.md)