Outlook

Access the Outlook API in 2 minutes 💨

🚀 Quickstart

1. Create an integration

   In Nango (free signup), go to Integrations -> Configure New Integration -> Outlook. Nango doesn’t provide a test OAuth app for Outlook yet. You’ll need to set up your own by following these instructions. After that, make sure to add the OAuth client ID, secret, and scopes in the integration settings in Nango.

2. Authorize Outlook

   Go to Connections -> Add Test Connection -> Authorize, then log in to Outlook. Later, you’ll let your users do the same directly from your app.

3. Call the Outlook API

   Let’s make your first request to the Outlook (Microsoft Graph) API (fetch the profile of the currently signed-in user). Replace the placeholders below with your secret key, integration ID, and connection ID:

   cURL

   curl "https://api.nango.dev/proxy/v1.0/me" \
     -H "Authorization: Bearer <NANGO-SECRET-KEY>" \
     -H "Provider-Config-Key: <INTEGRATION-ID>" \
     -H "Connection-Id: <CONNECTION-ID>"
   

   Node

   Install Nango’s backend SDK with npm i @nangohq/node. Then run:

   import { Nango } from '@nangohq/node';
   
   const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });
   
   const res = await nango.get({
       endpoint: '/v1.0/me',
       providerConfigKey: '<INTEGRATION-ID>',
       connectionId: '<CONNECTION-ID>'
   });
   
   console.log(res.data);
   

   Or fetch credentials dynamically via the Node SDK or API.

✅ You’re connected! Check the Logs tab in Nango to inspect requests.

Next step: Embed the auth flow in your app to let your users connect their Outlook accounts.

🧑‍💻 OAuth app setup

1. Create a Microsoft account and Azure account

   If you don’t already have them, sign up for a Microsoft account and an Azure account.

2. Register an application in Microsoft Entra ID

   1. Sign in to the Microsoft Entra admin center as at least an Application Developer.
   2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application.
   3. From the search bar at the top of the Azure portal, search for App registrations and select it. Then choose New registration. Or from your left navigation tab, navigate to Applications > App registrations then choose New registration.
   4. Enter a meaningful name for your application, for example “Nango Integration”.
   5. Under Supported account types you need to decide who can install your integration:
      • Accounts in any organizational directory - Any user account in a professional Microsoft organization (Business, School, etc.)
      • Accounts in any organizational directory and personal Microsoft accounts - The accounts from the first option, plus personal Microsoft accounts (pick this unless you want to restrict your integration to business accounts)
   6. Leave the Redirect URI section blank for now; we’ll configure it in a later step.
   7. Click Register to complete the app registration.
3. Note your application (client) ID

   After registration, you’ll be taken to the application’s Overview page. Record the Application (client) ID, which uniquely identifies your application and is used in your application’s code as part of validating security tokens.

4. Add a redirect URI

   1. In the left sidebar, select Authentication.
   2. Under Platform configurations, select Add a platform.
   3. Select Web as the platform type.
   4. Enter https://api.nango.dev/oauth/callback as the Redirect URI.
   5. Under Advanced settings, keep Allow public client flows set to the default No for web applications.
   6. Click Configure to save your changes.
5. Add API permissions

   1. In the left sidebar, select API permissions.
   2. Click Add a permission.
   3. Select Microsoft Graph to integrate with Outlook.
   4. Select the required permissions from the Delegated permissions section.
   5. Select the specific permissions your app requires. Please refer to the table below for some of the commonly used scopes.
   6. Click Add permissions.
   7. If your application requires admin consent, click Grant admin consent for [tenant] to pre-authorize the permissions.
6. Create a client secret

   1. In the left sidebar, select Certificates & secrets.
   2. Under Client secrets, click New client secret.
   3. Enter a description for the secret and select an expiration period (6 months, 12 months, 24 months, or custom). Please select a date further in the future to avoid interruptions. Note that the Custom date can only be set to a maximum of 1 year from the current date. If the secret expires, you will need to regenerate a new one and update your integration within Nango.
   4. Click Add.
   5. Important: Copy the secret value immediately and store it securely. You won’t be able to see it again after you leave this page.
7. Configure token settings (optional)

   1. In the left sidebar, select Token configuration. Here you can configure optional claims to be included in the access tokens issued for your application.
   2. Click Add optional claim and select the claims you want to include in your access tokens.
8. Configure app visibility (optional)

   If you want users to see your app on their My Apps page:

   1. From the search bar at the top of the Azure portal, search for Enterprise applications, select it, and then choose your app.
   2. On the Properties page, set Visible to users? to Yes.
9. Next

   Follow the Quickstart.

Common Scopes

Scope	Description
Mail.Read	Read the signed-in user’s email messages
Mail.ReadWrite	Read and write the user’s mail
Mail.Send	Send mail as the signed-in user
Mail.ReadWrite.Shared	Read and write mail shared with the user
Calendars.Read	Read the user’s calendar events
Calendars.ReadWrite	Read and write the user’s calendar events
Calendars.Read.Shared	Read shared calendars that the user has access to
Calendars.ReadWrite.Shared	Read and write shared calendars that the user has access to
Contacts.Read	Read the user’s contacts
Contacts.ReadWrite	Read and write the user’s contacts
offline_access	Access to refresh tokens for offline access
User.Read.All	Read user profiles in the organization

🔗 Useful links

Useful links

Topic	Links
General	Microsoft Entra Admin Center
	Azure Portal
	Microsoft Graph Explorer
Developer	Microsoft identity platform documentation
	Microsoft Graph API Overview
	How to register an Application
	OAuth 2.0 Authorization Code Flow
	Microsoft Graph Permissions Reference
	Microsoft Authentication Libraries (MSAL)
	Microsoft Graph API Reference
	Microsoft Graph Throttling Guidance
	Redirect URI Best Practices

Contribute useful links by editing this page

🚨 API gotchas

• You can find permissions required for each API call in their corresponding API methods section, i.e, to list messages from Outlook, you can have a look at List Messages permissions.

• Make sure you request the offline_access scope to get a refresh token and keep access with your integration.
• Microsoft offers a tool that allows you to construct and perform Graph API queries and see their response for any apps on which you have an admin, developer, or tester role. For more information you can check Microsoft Graph Explorer.
• Please be aware that the Microsoft Graph API implements throttling to manage the volume of requests. For more information on handling throttling, refer to the Microsoft Graph Throttling Guidance.
• Microsoft Graph API has different versions (v1.0 and beta). The v1.0 endpoint is for production use, while the beta endpoint contains features that are still in preview.
• When requesting permissions that require admin consent, users without admin privileges will not be able to complete the OAuth flow unless an admin has pre-authorized the permissions.
• For multitenant applications, you may need to handle tenant-specific endpoints and permissions.
• You can set the .default scope documentation to ensure the permissions remain the same as those granted at the organization level.
• The .default scope can’t be combined with the scopes registered in the Azure portal. So either just use the .default scope or remove it to list out explicit parameters that are required. If you attempt to combine them you’ll receive the following error

.default scope can't be combined with resource-specific scopes

• If you need a user to reauthenticate or accept updated scopes, you can force a prompt using the authorization_params. Use prompt=login to force the user to enter their credentials (bypassing single-sign on) or prompt=consent to trigger the OAuth consent dialog after sign-in, which asks the user to grant permissions to the app. For more details, see Microsoft’s OAuth 2.0 authorization documentation.

const { data } = await nango.createConnectSession({
  [...],
  integrations_config_defaults: {
    "<provider-name>": {
      authorization_params: {
        "prompt": "consent" // or "login" depending on your needs
      }
    }
  }
});

Contribute API gotchas by editing this page

Questions? Join us in the Slack community.