Skip to main content

Connect to Microsoft Graph

Connect Microsoft Graph to Retool to read and manage Microsoft 365 users, mail, calendars, files, and teams.

Microsoft Graph is the unified API for Microsoft 365 services, including Entra ID, Outlook, Teams, and SharePoint. Retool connects to Microsoft Graph through the Graph API v1.0 using OAuth 2.0 or Microsoft Azure Identity.

After you create a Microsoft Graph resource in Retool, you can:

  • Read and manage users, groups, and directory objects in Microsoft Entra ID.
  • Read, send, and organize email messages and mailbox folders.
  • Read and create calendar events and meetings.
  • List, upload, and manage files and folders in OneDrive and SharePoint.
  • Read and post messages to Microsoft Teams channels and chats.

If you only need to read or post Teams messages and channels, Microsoft Teams offers a simpler zero-configuration OAuth setup on Cloud instances. Use Microsoft Graph instead when you also need mail, calendar, user, or file data alongside Teams data in the same app, or when you need non-interactive authentication with Microsoft Azure Identity.

Before you begin​

To connect Microsoft Graph to Retool, you need the following:

  • Microsoft account: A Microsoft 365 or Entra ID account with access to the data you want to query.
  • Azure app registration: An app registration in Microsoft Entra ID if you use a custom OAuth 2.0 app or Microsoft Azure Identity.
  • Retool permissions: Edit all permissions for resources in your organization.

Create a Microsoft Graph resource​

Follow these steps to create a Microsoft Graph resource in your Retool organization.

1. Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for Microsoft Graph and click the Microsoft Graph tile to begin configuration.

Use folders to organize your resources by team, environment, or data source type. This helps keep your resource list manageable as your organization grows.

2. Configure general settings​

Specify a name and description for the resource that indicates which Microsoft account or tenant it connects to. The description provides more context to users and Assist about how to use the resource.

Example nameExample description
Microsoft GraphDefault Microsoft Graph resource for reading directory and mailbox data.
Microsoft Graph (Mail)Microsoft Graph resource scoped to mailbox data for the support ticketing app.

When using OAuth 2.0, you typically only need one resource per Azure app registration. Each user authenticates individually and can only access their own data. Creating multiple resources is usually unnecessary unless you need to support multiple Azure app registrations or different scope combinations.

3. Configure authentication​

Configure the connection settings for your Microsoft Graph resource under the Credentials section of the resource configuration form. Both authentication methods require an app registration in Microsoft Entra ID. Microsoft Graph has no zero-configuration hosted OAuth option.

Microsoft Graph resource configuration form.

Microsoft Graph supports two authentication methods. Choose based on whether queries should run as the signed-in user or as a non-interactive service identity.

Authentication methodUse cases
OAuth 2.0Interactive apps where each user authenticates with their own Microsoft account. Each user only sees the data they have access to.
Microsoft Azure IdentityAutomated workflows, scheduled queries, and shared internal apps that need to act as a non-interactive service identity using an Entra app registration.
option A: OAuth 2.0
  1. Register an app in Microsoft Entra ID.
  2. In Retool, select OAuth 2.0 as the Authentication method.
  3. Choose one or more Scopes from the available Microsoft Graph permissions. The default scopes are User.Read and offline_access.
  4. Copy the OAuth callback URL shown in the form and add it as a redirect URI on your Entra app registration.
  5. Enter the Client ID and Client secret from your app registration.
  6. Optionally check Override authorization URLs to use non-default authorization or token endpoints, for example when connecting to a specific Entra tenant instead of the common endpoint.
  7. Optionally enable Share credentials between users to allow all users of the resource to share a single set of credentials. By default, each user authenticates individually.
  8. Click Connect with OAuth and sign in with your Microsoft account.
  9. Click Create resource to save.

The OAuth callback URL for Cloud organizations is https://oauth.retool.com/oauth/user/oauthcallback.

option B: Microsoft Azure Identity

Use Azure Identity when queries should run as a non-interactive service identity rather than as the signed-in user.

  1. Register an app in Microsoft Entra ID and grant it the application permissions your queries need.
  2. In Retool, select Microsoft Azure Identity as the Authentication method.
  3. Enter one or more Scopes, space-separated. The default scope is https://graph.microsoft.com/.default.
  1. Enter the Tenant ID (the Microsoft Entra tenant, or directory, ID) and the Client ID of the app registration.
  2. Enter the Client Secret generated for the app registration.
  3. Click Create resource to save.

Outbound region​

By default, requests originate from your organization's outbound region (for example, us-west-2). Enable Override default outbound Retool region to route requests through a different region.

4. Save the resource​

Click Create resource to save your Microsoft Graph resource.

Microsoft Graph resources cannot be tested from the resource configuration screen. Save the resource and verify the connection by running a query—for example, get the signed-in user's profile at https://graph.microsoft.com/v1.0/me.

Query Microsoft Graph data​

Once you've created a Microsoft Graph resource, you can query it in apps, workflows, and agent tools. Microsoft Graph queries call the Graph API v1.0 directly. Retool provides an Operation field for the endpoint path and HTTP method, plus a request body, headers, and URL parameters scoped to that endpoint.

Create a query​

Microsoft Graph isn't yet available as a resource in the new app builder. In classic apps, you can create a Microsoft Graph query manually by selecting an operation, or use Assist to generate one with natural language.

To manually create a Microsoft Graph query in a classic app:

  1. In the classic app IDE, open the Code tab, then click + in the page or global scope.
  2. Select Resource query.
  3. Choose your Microsoft Graph resource.
  4. In the Operation field, enter the endpoint path and HTTP method (for example, /me GET).
  5. Configure any URL parameters, request body, or headers required by the endpoint, then run the query.

Query configuration fields​

The following fields are specific to the classic app query editor—for the full list of available Graph API endpoints and parameters, refer to the Graph API reference.

Operation​

Specify the endpoint path and HTTP method as a single value. The base URL https://graph.microsoft.com/v1.0 is prepended automatically—provide everything after that. The path can include path parameters such as a user or item ID.

Examples
# Get the signed-in user
/me GET

# List users in the tenant
/users GET

# Get a specific user's manager
/users/{{ userIdInput.value }}/manager GET

# Send an email as the signed-in user
/me/sendMail POST

# Delete a calendar event
/me/events/{{ table1.selectedRow.data.id }} DELETE

URL parameters​

Add URL parameters in the URL parameters section of the query editor to pass query-string arguments to the endpoint. Path parameters (like a user ID) belong in the Operation path, not here. Common URL parameters include:

ParameterDescriptionExample
$filterFilters results using OData query syntax.startswith(displayName,'{{ searchInput.value }}')
$selectA comma-separated list of properties to include in the response. Reduces payload size.id,displayName,mail
$topMaximum number of items to return per page.50
$orderbySorts results by one or more properties.displayName asc
$expandIncludes related resources in the same response.manager

Request body​

For write operations (POST, PATCH), provide a JSON body matching the Graph API resource schema for the endpoint. Use embedded expressions to interpolate values from app state.

Example: send an email
{
  "message": {
    "subject": {{ subjectInput.value }},
    "body": {
      "contentType": "Text",
      "content": {{ bodyInput.value }}
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": {{ emailInput.value }}
        }
      }
    ]
  }
}

Advanced​

Use the Advanced section to add request headers or URL parameters not covered by the operation's defaults. The Authorization header is set automatically from the resource's authentication.

Microsoft Graph query examples​

These examples use the classic app query editor and demonstrate common Microsoft Graph operations in classic apps. For a complete reference of available operations and parameters, refer to the Graph API documentation.

get the signed-in user's profile

Create a query named meQuery to retrieve the signed-in user's profile.

Configure the query:

FieldValue
Operation/me GET

Add a Text component and set its Value to {{ meQuery.data.displayName }}.

list users in the tenant

Create a query named listUsersQuery to list users, filtered and sorted server-side.

Configure the query:

FieldValue
Operation/users GET
URL parameters$filter=startswith(displayName,'{{ searchInput.value }}')
$select=id,displayName,mail,jobTitle
$top=50
$orderby=displayName asc

Add a Table component and set its Data property to {{ listUsersQuery.data.value }}.

send an email as the signed-in user

Create a query named sendMailQuery to send an email from a form.

Configure the query:

FieldValue
Operation/me/sendMail POST

Set the Request body to:

{
  "message": {
    "subject": {{ form1.data.subject }},
    "body": {
      "contentType": "Text",
      "content": {{ form1.data.body }}
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": {{ form1.data.recipient }}
        }
      }
    ]
  }
}

Add an event handler to the form's Submit event that runs sendMailQuery and shows a success notification.

list upcoming calendar events

Create a query named listEventsQuery to list the signed-in user's upcoming calendar events.

Configure the query:

FieldValue
Operation/me/events GET
URL parameters$select=subject,start,end,organizer
$orderby=start/dateTime asc
$top=20

Add a Table component and set its Data property to {{ listEventsQuery.data.value }}.

post a message to a Teams channel

Create a query named postMessageQuery to post a message to a Microsoft Teams channel.

Configure the query:

FieldValue
Operation/teams/{{ teamIdInput.value }}/channels/{{ channelIdInput.value }}/messages POST

Set the Request body to:

{
  "body": {
    "content": {{ messageInput.value }}
  }
}

Add an event handler to a button's Click event that runs postMessageQuery and clears the message input on success.

Best practices​

Follow these best practices to optimize performance, maintain security, and ensure data integrity when working with REST APIs.

Performance​

  • Cache responses: For data that doesn't change frequently, enable query caching to reduce API calls and improve response times.
  • Use pagination: Implement pagination for endpoints that return large datasets to reduce payload size and improve performance.
  • Batch requests: When available, use batch API endpoints to combine multiple operations into a single request.
  • Minimize payload size: Request only the fields you need using query parameters or API-specific field selection features.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.

Security​

  • Use configuration variables: Store API keys and tokens in configuration variables or secrets rather than hardcoding them.
  • Use HTTPS only: Always connect to APIs over HTTPS to encrypt data in transit and protect authentication credentials.
  • Rotate credentials regularly: Follow your API provider's recommendations for credential rotation and key management.
  • Validate SSL certificates: Keep SSL certificate verification enabled unless absolutely necessary for development environments.
  • Use resource environments: Configure multiple resource environments to maintain separate API configurations for production, staging, and development.
  • Apply least privilege: Use API keys with minimal required permissions. Create separate keys for different environments.

Data integrity​

  • Validate user input: Sanitize and validate all user input before including it in API requests to prevent injection attacks.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed API calls to improve user experience.
  • Use idempotency keys: For APIs that support idempotency keys, include them in POST/PATCH requests to prevent duplicate operations.
  • Verify responses: Check response status codes and validate response data structure before using it in your app.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.

Microsoft Graph-specific considerations​

  • Request only the scopes you need: Choose the narrowest set of scopes for your use case. Adding broader scopes later forces every user to re-consent.
  • Use $select to reduce payload size: Many Graph endpoints return large objects by default. Specifying $select reduces response size and improves performance.
  • Handle paginated responses: List endpoints return an @odata.nextLink property when more results are available. Use it to fetch subsequent pages.
  • Application permissions require admin consent: Scopes used with Microsoft Azure Identity are application permissions and typically require a tenant administrator to grant consent in the Azure portal before they take effect.
  • Respect throttling limits: Microsoft Graph enforces per-tenant and per-app rate limits. Implement retry logic with backoff for 429 Too Many Requests responses, using the Retry-After header.