APIs & Integrations
SharePoint Online (v2)
Overview
Pre-built tooling
Pre-built integrations
Not seeing the integration you need? Build your own independently.
Access requirements
Pre-Requisites | Status | Comment |
---|---|---|
Paid dev account | ✅ Not required | Free, self-signup for a Microsoft account and Azure account. |
Paid test account | ✅ Not required | Free Microsoft account can be used for testing. |
Partnership | ✅ Not required | |
App review | ⚠️ Conditional | Required only if you want to publish your app to the Microsoft commercial marketplace or if your app needs admin consent for certain permissions. |
Security audit | ✅ Not required |
Setup guide
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
- Sign in to the Microsoft Entra admin center as at least an Application Developer.
- 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.
- From the search bar at the top of the Azure portal, search for App registrations and select it. Then choose New registration.
- Enter a meaningful name for your application, for example “Nango Integration”.
- Under Supported account types, select the appropriate option based on your needs:
- Accounts in this organizational directory only - For single-tenant apps for use only by users in your tenant.
- Accounts in any organizational directory - For multitenant apps that you want users in any Microsoft Entra tenant to be able to use.
- Accounts in any organizational directory and personal Microsoft accounts - For multitenant apps that support both organizational and personal Microsoft accounts.
- Personal Microsoft accounts - For apps used only by personal Microsoft accounts.
- Leave the Redirect URI section blank for now; we’ll configure it in a later step.
- 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
- In the left sidebar, select Authentication.
- Under Platform configurations, select Add a platform.
- Select Web as the platform type.
- Enter
https://api.nango.dev/oauth/callback
as the Redirect URI. - Under Implicit grant and hybrid flows, check the boxes for Access tokens and ID tokens if your application needs them.
- Under Advanced settings, set Allow public client flows to No for web applications.
- Click Configure to save your changes.
5
Add API permissions
- In the left sidebar, select API permissions.
- Click Add a permission.
- Select Microsoft Graph to integrate with SharePoint Online (v2).
- Choose the type of permissions:
- Delegated permissions - Your app accesses the API as the signed-in user.
- Application permissions - Your app accesses the API directly without a signed-in user.
- Select the specific permissions your app requires, Please refer to the table below for some of the commonly used scopes.
- Click Add permissions.
- If your application requires admin consent, click Grant admin consent for [tenant] to pre-authorize the permissions.
6
Create a client secret
- In the left sidebar, select Certificates & secrets.
- Under Client secrets, click New client secret.
- Enter a description for the secret and select an expiration period (6 months, 12 months, 24 months, or custom).
- Click Add.
- 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)
- In the left sidebar, select Token configuration.
- Here you can configure optional claims to be included in the ID and access tokens issued to your application.
- Click Add optional claim if you need to include additional information in your tokens.
8
Configure app visibility (optional)
If you want users to see your app on their My Apps page:
- From the search bar at the top of the Azure portal, search for Enterprise applications, select it, and then choose your app.
- On the Properties page, set Visible to users? to Yes.
9
Next
Follow the Quickstart.
Useful links
Contribute useful links by editing this page
Common Scopes
Scope | Description |
---|---|
Sites.Read.All | Read SharePoint sites and lists across the organization |
Sites.ReadWrite.All | Read and write SharePoint sites and lists across the organization |
Sites.Manage.All | Full control of all site collections without a signed-in user |
Sites.FullControl.All | Have full control of all site collections (includes manage, read/write) |
Files.Read | Read user files and file properties |
Files.Read.All | Read all files the user can access |
Files.ReadWrite | Read and write user files |
Files.ReadWrite.All | Read and write all files the user can access |
offline_access | Access to refresh tokens for offline access |
User.Read.All | Read user profiles in the organization (useful if mapping users to files) |
API gotchas
- Nango supports both SharePoint Online v1 and v2, providing flexibility for integrations depending on your requirements. SharePoint v1 refers to the older REST API, which uses legacy authentication methods like SharePoint Online (SPO) or older OAuth implementations. Its endpoints follow the pattern
https://<your-tenant>.sharepoint.com/_api/
, and it supports basic SharePoint operations. However, v1 lacks modern features such as delta queries for incremental sync and deep integration with Microsoft 365. - Sharepoint Online v2, on the other hand, is a modernized version aligned with the Microsoft Graph API. It uses OAuth 2.0 with the Microsoft Identity Platform (formerly Azure AD) for secure and scalable authentication. Endpoints for v2 are primarily accessed through
https://graph.microsoft.com/v1.0/sites/...
, and it offers advanced capabilities like delta queries for incremental sync, enhanced performance, and seamless integration with Microsoft 365 services. - You can find permissions required for each API call in their corresponding API methods section, i.e, to get metadata for a list from Sharepoint, you can have a look at Get metadata for a list 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
- If you require a user to reauthenticate and force them to accept scopes that have been updated or changed you can force a prompt via the
authorization_params
:
Contribute API gotchas by editing this page