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

# Connect to Microsoft 365 with the Microsoft Graph API

> Register an app in Microsoft Entra ID and connect Superblocks to Outlook, SharePoint, and Teams through the Microsoft Graph API

## Overview

Microsoft 365 services like Outlook (Exchange), OneDrive, SharePoint, and Teams are all accessed through the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview). In Superblocks, you connect to Microsoft Graph with a [REST API](/integrations/integrations-library/rest-api) integration that authenticates using [OAuth 2.0](/integrations/auth/oauth-20).

Each integration is backed by an **app registration** in Microsoft Entra ID. The app registration provides the client ID and secret Superblocks uses to request tokens, and its **API permissions** control what Superblocks can do in Microsoft 365.

This guide walks through:

1. Creating an app registration in Microsoft Entra ID
2. Granting Microsoft Graph permissions
3. Creating the integration in Superblocks
4. Building an app with Clark using your Microsoft 365 integrations

## Prerequisites

* Access to the [Microsoft Entra admin center](https://entra.microsoft.com) or [Azure portal](https://portal.azure.com) with permission to create app registrations
* A Microsoft Entra admin available to grant admin consent, if your tenant requires it for the permissions you choose
* Permission to create integrations in Superblocks

## Choose a permission type

When you add Microsoft Graph permissions to an app registration, you choose between two types:

| Permission type | Acts as | Superblocks auth method | Use when |
| - | - | - | - |
| **Delegated** | The user logged in to Superblocks | [OAuth2 - Authorization Code](/integrations/auth/oauth-20#authorization-code) | Users should only see and act on data they already have access to in Microsoft 365, such as their own inbox or the Teams channels they belong to |
| **Application** | The app itself, like a service account | [OAuth2 - Client Credentials Grant](/integrations/auth/oauth-20#client-credential) | Background processes, such as Workflows or Scheduled Jobs, that need access without a user present |

This guide uses **delegated** permissions with the Authorization Code flow, so each user authorizes with their own Microsoft identity and Microsoft 365 enforces their existing access.

Integrations that use Authorization Code without a shared token prompt each user to log in, so they can't be used in Workflows or Scheduled Jobs. For background use, configure application permissions and the Client Credentials flow instead.

## Setup

**1. Create an app registration**

1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity** → **Applications** → **App registrations** and click **New registration**.

2. Give the app a descriptive name, such as `Superblocks - Outlook`.

3. Under **Supported account types**, select **Accounts in this organizational directory only**.

4. Under **Redirect URI**, select the **Web** platform and enter:

   ```text theme={null}
   https://{tenant}.superblocks.com/oauth/callback
   ```

   Replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). You can also copy the exact **Callback URL** from the Superblocks integration form in a later step.

5. Click **Register**.

6. From the app's **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID**.

Create a separate app registration for each Microsoft 365 service you connect, such as one for mail, one for SharePoint, and one for Teams. This keeps each integration scoped to only the permissions it needs.

**2. Create a client secret**

1. In the app registration, go to **Certificates & secrets** → **Client secrets** and click **New client secret**.
2. Add a description, choose an expiration, and click **Add**.
3. Copy the secret's **Value** right away. It's only shown once.

When the client secret expires, the integration stops working. Track the expiration date and rotate the secret in Superblocks before it expires.

**3. Add Microsoft Graph API permissions**

1. In the app registration, go to **API permissions** and click **Add a permission**.

2. Select **Microsoft Graph**, then **Delegated permissions**.

3. Add the permissions for the service this integration connects to. For example:

   | Service | Example delegated permissions |
   | - | - |
   | **Outlook / Exchange mail** | `User.Read`, `Mail.ReadWrite`, `Mail.Send` |
   | **OneDrive** | `User.Read`, `Files.ReadWrite` |
   | **SharePoint** | `User.Read`, `Files.ReadWrite.All`, `Sites.ReadWrite.All` |
   | **Teams** | `User.Read`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`, `ChannelMessage.Send` |

4. If any permission shows **Admin consent required**, ask a Microsoft Entra admin to click **Grant admin consent** for your organization.

Grant only the permissions your app needs. See Microsoft's [permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for the full list and what each one allows.

**4. Create the integration in Superblocks**

1. Create a [REST API integration](/integrations/integrations-library/rest-api) in Superblocks and give it a name that identifies the service, such as `Microsoft Graph - Outlook`.

2. Set **Base URL** to `https://graph.microsoft.com/v1.0`.

3. Under **Authentication**, select **OAuth2 - Authorization Code** and fill in:

   | Field | Value |
   | - | - |
   | **Authorization URL** | `https://login.microsoftonline.com/{directory-tenant-id}/oauth2/v2.0/authorize` |
   | **Token URL** | `https://login.microsoftonline.com/{directory-tenant-id}/oauth2/v2.0/token` |
   | **Client ID** | The **Application (client) ID** from your app registration |
   | **Client secret** | The client secret **Value** you copied |
   | **Scopes** | `https://graph.microsoft.com/.default offline_access` |
   | **Prompt** | `select_account` |

   Replace `{directory-tenant-id}` with the **Directory (tenant) ID** from your app registration.

   The `.default` scope requests all of the Microsoft Graph permissions configured on your app registration, so you don't need to list them individually. `offline_access` must be requested explicitly so Superblocks receives a refresh token and can renew access without prompting users to sign in again. Don't add individual Graph permissions alongside `.default`; Microsoft rejects requests that combine them.

   Don't set **Prompt** to `consent`. Because of a [known Microsoft Entra ID issue](https://learn.microsoft.com/en-us/answers/questions/5847660/bug-report-prompt-consent-blocks-non-admin-users-e), `prompt=consent` blocks non-admin users with a "Need admin approval" (`AADSTS90094`) error, even after an admin has granted tenant-wide consent. `select_account` honors the existing admin consent and lets users sign in.

4. Confirm the **Callback URL** shown in the form matches the redirect URI on your app registration. If it doesn't, add it under **Authentication** in the app registration.

5. Under **Headers**, add an `Authorization` header with the value `Bearer {{ oauth.token }}`.

6. Click **Create** to save the integration.

Repeat this step for each Microsoft 365 service, using that service's app registration and scopes.

## Build with Clark

### Teach Clark about your integrations

Clark already knows Microsoft Graph from its public documentation, but it doesn't know the specifics of your tenant, like which SharePoint site and drive to use, which Teams channel to post to, or how your mailboxes are organized. Capture these details as [integration knowledge](/integrations/knowledge) so Clark looks them up whenever it works with that integration.

The easiest way to build this knowledge is to have Clark explore your integrations first:

1. Create a new app so the exploration doesn't affect an existing one.

2. [Tag your integrations](/building-with-clark/tagging-integrations) with `@` and ask Clark to explore them. For example:

   ```text theme={null}
   Explore @Microsoft Graph - SharePoint and @Microsoft Graph - Teams. Find our
   SharePoint sites and their document libraries, and the Teams channels I have access to.
   Note the IDs and request patterns you'd need to upload files and post messages.
   ```

3. Review what Clark finds, then ask it to save the insights to integration knowledge:

   ```text theme={null}
   Save what you learned about each integration to its integration knowledge.
   ```

Clark drafts an entry for each integration and presents it for your review before saving. Useful details to capture include site, drive, team, and channel IDs, the endpoints and request shapes that worked, and any quirks Clark ran into, such as pagination or required headers. Anyone who builds with these integrations later benefits from the same knowledge.

### Build an app

Once your integrations are set up, you can have Clark build apps on top of them. Tag your integrations in your prompt with `@` so Clark uses them as data sources. For example:

```text theme={null}
Build an AP invoice audit desk that reads invoice emails from @Microsoft Graph - Outlook,
archives each invoice and an audit record to our SharePoint drive using
@Microsoft Graph - SharePoint, and posts a confirmation to our finance channel
with @Microsoft Graph - Teams.
```

Because these integrations use the Authorization Code flow, you're prompted to sign in with your Microsoft account when Clark first queries them. Clark then runs sample requests against Microsoft Graph to understand your data, such as pulling recent messages from your inbox, listing files in your SharePoint drive, and finding the Teams channels you have access to. It uses what it learns to ask clarifying questions and propose a plan before building. See [Plan & Build modes](/building-with-clark/plan-and-build-modes) for how planning works.

When users run the finished app, each user signs in with their own Microsoft account and only sees the mail, files, and channels they have access to in Microsoft 365.

## Troubleshooting

### Users see "Need admin approval" (AADSTS90094)

If non-admin users are blocked with a "Need admin approval" screen when they sign in:

1. Confirm a Microsoft Entra admin has clicked **Grant admin consent** on the app registration's **API permissions** page, and that each permission shows a **Granted** status.
2. In the Superblocks integration, set **Prompt** to `select_account`. If **Prompt** is set to `consent`, Microsoft Entra ID ignores the existing admin consent and asks each user to consent for themselves, which your tenant's consent policy blocks. See Microsoft's [bug report](https://learn.microsoft.com/en-us/answers/questions/5847660/bug-report-prompt-consent-blocks-non-admin-users-e) for details.

## Related documentation

* [OAuth 2.0](/integrations/auth/oauth-20): details on each OAuth flow, token caching, and refresh
* [REST API integration](/integrations/integrations-library/rest-api): REST API integration settings, including uploading OpenAPI specs
* [Tagging integrations](/building-with-clark/tagging-integrations): reference integrations in your Clark prompts
* [Integration knowledge](/integrations/knowledge): teach Clark how to work with each integration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.