Skip to main content

​
Overview

Microsoft 365 services like Outlook (Exchange), OneDrive, SharePoint, and Teams are all accessed through the Microsoft Graph API. In Superblocks, you connect to Microsoft Graph with a REST API integration that authenticates using OAuth 2.0. 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 or Azure portal 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: 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.

​
Setup

1

Create an app registration

  1. In the Microsoft Entra admin center, 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:
    Replace {tenant} with the value for your instance from 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.
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.
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:
  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 for the full list and what each one allows.
4

Create the integration in Superblocks

  1. Create a REST API integration 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: 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.
  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 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 with @ and ask Clark to explore them. For example:
  3. Review what Clark finds, then ask it to save the insights to 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:
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 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 for details.