OneDrive API Integration Using Microsoft Graph (Step-by-Step Guide)

OneDrive API Integration Using Microsoft Entra (Graph API)

This guide explains how to build an end-to-end integration with Microsoft OneDrive using the Microsoft Graph API, supporting both business (work/school) and personal (consumer) Microsoft accounts.

You will learn how to register an app, configure authentication, request tokens, and call common OneDrive API endpoints.

Step 1: Register an App in Microsoft Entra

Go to https://entra.microsoft.com and go to Azure Active Directory > App registrations > New registration.

Fill in the following:

• Name: OneDrive Integration
• Supported account types: Accounts in any organizational directory and personal Microsoft accounts
• Redirect URI: https://yourapp.com/callback (or http://localhost:3000 for testing)

Click Register, then save the Application (client) ID and Directory (tenant) ID.

Step 2: Add Redirect URI

After registration, go to the app’s Authentication tab and add all required URIs under Redirect URIs.

Step 3: Configure API Permissions

Navigate to API permissions > Add a permission > Microsoft Graph > Delegated:

Essential Permissions

• User.Read: sign in and read user profile
• Files.ReadWrite.All: full access to user’s OneDrive and SharePoint files
• Sites.Read.All: access SharePoint site content
• offline_access: allows use of refresh tokens

Click Grant admin consent for the tenant (recommended for business apps).

Understanding OneDrive API Permissions (Delegated vs Application)

Why Use Delegated Over Application?

• Some OneDrive endpoints (like /me/drive) only support delegated access
• If using a personal Microsoft account (@outlook.com), application permissions are not supported
• Delegated flow is easier to test interactively
• Application permissions require admin consent, which may not be available in development/testing environments.

Step 4: Get Client ID and Secret for OneDrive API Integration

Go to Certificates & secrets > New client secret. Add a name and expiration, then save the secret value immediately it will not be shown again.

Step 5: OneDrive API OAuth 2.0 Flow Explained (Step-by-Step)

Authorization URLs

Sample Authorization Request (GET)

GET /oauth2/v2.0/authorize
  ?client_id={client_id}
  &response_type=code
  &redirect_uri={redirect_uri}
  &response_mode=query
  &scope=User.Read Files.ReadWrite.All Sites.Read.All offline_access
  &state=12345

Exchange Code for Access Token

POST to https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token (or use /consumers/ or /common/)

Content-Type: application/x-www-form-urlencoded

client_id={client_id}
&scope=User.Read Files.ReadWrite.All Sites.Read.All offline_access
&code={authorization_code}
&redirect_uri={redirect_uri}
&grant_type=authorization_code
&client_secret={client_secret}

It can be hard to keep track of authentication across systems when you use more than one API, especially in accounting and ERP workflows.

Check out how our accounting automation solutions make this easier.

Refresh Token Flow

POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}
&client_secret={client_secret}
&scope=User.Read Files.ReadWrite.All Sites.Read.All offline_access

After the user completes the OAuth consent flow, Microsoft returns an authorization code to your redirect URI.

Your application must exchange this authorization code for an access token.

The access token is used to call OneDrive API endpoints through Microsoft Graph.

Every API request must include the token in the authorization header:

Authorization: Bearer {access_token}

Access tokens are short-lived. Once the access token expires, your application should use the refresh token to request a new access token without asking the user to sign in again.

The refresh token is only available when the offline_access scope is requested during the authorization process.

This is important for applications that need long-running file sync, background upload, or scheduled document processing.

Best practices for handling OneDrive API tokens:

• Store access tokens and refresh tokens securely.
• Never expose tokens in frontend code.
• Refresh the access token before making background API calls.
• Re-authenticate the user if the refresh token is revoked or expired.
• Use delegated permissions when working with personal Microsoft accounts.

Here is a quick reference for commonly used OneDrive API endpoints through Microsoft Graph.

Get user drive:
GET /me/drive

List root files and folders:
GET /me/drive/root/children

Create folder in root:
POST /me/drive/root/children

Create folder under another folder:
POST /me/drive/items/{parent_folder_id}/children

Upload small file:
PUT /me/drive/items/{parent-id}:/{filename}:/content

Get file versions:
GET /me/drive/items/{item-id}/versions

Restore file version:
POST /me/drive/items/{item-id}/versions/{version-id}/restoreVersion

Rename file or folder:
PATCH /me/drive/items/{item-id}

Move file or folder:
PATCH /me/drive/items/{item-id}

Copy file:
POST /me/drive/items/{item-id}/copy

Delete file or folder:
DELETE /me/drive/items/{item-id}

This quick reference gives developers a clear view of the most common file and folder operations before they go into the detailed API examples.

Common OneDrive API Endpoints File and Folder Operations

All requests must include the header: Authorization: Bearer {access_token}

Get Root Directory

Lists items in the user’s OneDrive root.

GET https://graph.microsoft.com/v1.0/me/drive/root/children

Create New Root Folder

POST https://graph.microsoft.com/v1.0/me/drive/root/children

{
  "name": "New Folder",
  "folder": {},
  "@microsoft.graph.conflictBehavior": "rename"
}

Create a Folder Under Another Folder

POST /me/drive/items/{parent_folder_id}/children

{
  "name": "New Child Folder",
  "folder": {},
  "@microsoft.graph.conflictBehavior": "rename"
}

Rename Folder

PATCH https://graph.microsoft.com/v1.0/me/drive/items/{item-id}

{
  "name": "New Folder Name"
}

Upload File

Uploads a small file directly to OneDrive. Ensure content-type matches file (e.g., image/png).

The request payload should be binary data of the file.

PUT /me/drive/items/{parent-id}:/{filename}:/content

Get File Versions

GET /me/drive/items/{item-id}/versions

Restore Specific Version

POST /me/drive/items/{item-id}/versions/{version-id}/restoreVersion

Delete File

DELETE /me/drive/items/{item-id}

Move File to Another Folder

PATCH /me/drive/items/{item-id}

{
  "parentReference": { "id": "destination-folder-id" }
}

Copy File

Creates a duplicate of the file in a new location. Use the Location header to monitor the async operation.

POST /me/drive/items/{item-id}/copy

{
  "parentReference": { "id": "destination-folder-id" },
  "name": "new-filename.ext"
}

Revoke User Sessions / Access

Revokes the user’s session and refresh tokens (Azure AD accounts only).

POST /me/revokeSignInSessions

Revoke App Consent via Portal (Manual)

Users can take back their permission for your app to access their information if they no longer want to:

• For personal Microsoft accounts (like Outlook.com, Hotmail.com, and Live.com): https://account.live.com/consent/Manage
• Work/School (Azure AD) accounts: https://myaccount.microsoft.com/ → Apps and sessions.

To upload a file to OneDrive, use the Microsoft Graph upload endpoint. For small files, you can upload the file content directly using a PUT request.

Example endpoint:

PUT /me/drive/items/{parent-id}:/{filename}:/content

In this endpoint:

• {parent-id} is the ID of the folder where the file should be uploaded.
• {filename} is the name of the file you want to create in OneDrive.
• The request body should contain the binary content of the file.
• The request must include the access token in the Authorization header.

Example request:

PUT https://graph.microsoft.com/v1.0/me/drive/items/{parent-id}:/{filename}:/content

Authorization: Bearer {access_token}
Content-Type: application/octet-stream

{binary-file-content}

For larger files, it is better to use an upload session.

Upload sessions allow your application to upload a file in multiple chunks, which is more reliable for large documents, videos, backups, or files uploaded over unstable networks.

Use direct upload for simple and small files. Use upload sessions when the file size is large or when you need resumable upload support.

Useful Links

• Microsoft Graph Docs
• Authentication Scenarios
• Register Your App
• Common API Docs

While integrating OneDrive API with Microsoft Graph, developers may face authentication, permission, or endpoint-related errors. Here are some common issues and how to fix them

Invalid Redirect URI

This error occurs when the redirect URI in your OAuth request does not exactly match the redirect URI configured in Microsoft Entra.

To fix it, check the redirect URI in your app registration and make sure it matches the URI used in your authorization request.

401 Unauthorized

A 401 error usually means the access token is missing, expired, invalid, or not passed correctly in the API request.

To fix it, send the access token in the Authorization header:

Authorization: Bearer {access_token}

If the token is expired, use the refresh token to get a new access token.

403 Forbidden

A 403 error usually means the app does not have the required permissions to access the requested OneDrive resource.

To fix it, review the Microsoft Graph permissions added to your app.

For file operations, permissions like Files.ReadWrite.All may be required. For business apps, admin consent may also be needed.

Invalid Client Secret

This error occurs when the client secret is incorrect, expired, or copied incorrectly.

To fix it, create a new client secret from Microsoft Entra and update it in your application configuration.

Refresh Token Not Returned

If the refresh token is not returned, check whether the offline_access scope was included in the authorization request.

Without offline_access, your application may not receive a refresh token, which can break background sync or long-running file operations.

OneDrive API Integration FAQs

Can I use my personal Microsoft account with the OneDrive API?

Yes, but you have to use delegated permissions with the /consumers or /common OAuth endpoint. Personal accounts do not support application permissions.

What do the /common, /consumers, and /organizations endpoints do that is different?

The /common endpoint supports both personal and work/school accounts. Use /consumers for personal-only and /organizations for work/school-only authentication flows.

How do I get a new access token after it has expired?

Send a POST request to the token endpoint with grant_type=refresh_token along with your client_id, client_secret, and the stored refresh_token. The offline_access scope must have been requested initially.

Why do I get a 403 error when calling OneDrive endpoints?

This usually means your app lacks the required permissions. Ensure you have granted Files.ReadWrite.All and the admin consent has been granted for your tenant.