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

OneDrive API Integration Using Microsoft Entra (Graph API)

Microsoft OneDrive API allows developers to connect applications with OneDrive for file storage, retrieval, sharing, and document management.

Using the Microsoft Graph API, applications can access OneDrive files and folders through REST endpoints with OAuth 2.0 authentication.

To integrate OneDrive API with your application, you need to register an application in Microsoft Entra ID, configure Microsoft Graph API permissions, obtain an OAuth access token, and use the appropriate API endpoints to perform file operations.

This OneDrive API integration guide covers both personal Microsoft accounts and Microsoft 365 work or school accounts. You’ll learn how to:

• Register an application and configure API access.
• Generate and manage OneDrive access tokens.
• Understand OneDrive API keys, client IDs, and secrets.
• Upload, download, and manage files using Microsoft Graph.
• Troubleshoot authentication, permissions, and API errors.

How to Access OneDrive API Using Microsoft Graph

To access OneDrive API, developers use Microsoft Graph, Microsoft’s unified API for accessing OneDrive and other Microsoft 365 resources.

Follow these steps:

1. Sign in to the Microsoft Entra admin center.
2. Register a new application.
3. Configure the Microsoft Graph permissions required for your integration.
4. Set up OAuth 2.0 authentication.
5. Obtain an access token.
6. Make authenticated requests to Microsoft Graph endpoints.

For example, the following API request retrieves the signed-in user’s OneDrive information:

GET https://graph.microsoft.com/v1.0/me/drive
Authorization: Bearer {access_token}

The /me/drive endpoint requires delegated user authentication. Applications using app-only authentication must access an appropriate user or drive resource instead.

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 OneDrive API Permissions

After registering your application, navigate to API permissions > Add a permission > Microsoft Graph.

Choose delegated permissions when the application accesses files on behalf of a signed-in user.

Choose application permissions when a background service needs access without an interactive user session.

Select only the permissions required for your use case.

For a basic OneDrive upload integration using delegated authentication, Files.ReadWrite is generally an appropriate starting point.

Administrator consent depends on the permission type and organizational consent policies. Application permissions require administrator consent.

Always follow the principle of least privilege when configuring Microsoft Graph access.

Microsoft’s permissions reference explains the available permission levels for file upload operations.

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

Open your application registration in Microsoft Entra ID.

Copy the Application (client) ID and Directory (tenant) ID from the Overview page.

For a confidential server-side application requiring a client secret, navigate to Certificates & secrets > Client secrets > New client secret.

Create the secret and save its value securely. Microsoft displays the secret value only when it is created.

Public clients, such as browser-based single-page applications, should not store client secrets. These applications typically use authorization code flow with PKCE.

Does OneDrive API Require an API Key?

OneDrive API does not use a conventional static API key for Microsoft Graph authentication.

Instead, applications authenticate using OAuth 2.0 access tokens issued by the Microsoft identity platform.

The key authentication components include:

• Client ID: Identifies the registered application.
• Tenant ID: Identifies the Microsoft Entra tenant for organizational authentication.
• Client secret or certificate: Authenticates a confidential application when required.
• Access token: Authorizes requests to Microsoft Graph APIs.

For example, authenticated OneDrive API requests include:

GET https://graph.microsoft.com/v1.0/me/drive/root/children
Authorization: Bearer {access_token}

Developers searching for a OneDrive API key typically need to create a Microsoft Entra application and configure the appropriate OAuth authentication flow instead.

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

Authorization URLs

Sample Authorization Request (GET)

Scopes are space-separated. In actual requests, encode each space as %20, for example User.Read%20Files.ReadWrite%20offline_access.

GET /oauth2/v2.0/authorize
  ?client_id={client_id}
  &response_type=code
  &redirect_uri={redirect_uri}
  &response_mode=query
  &scope=User.Read%20Files.ReadWrite%20offline_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%20Files.ReadWrite%20offline_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%20Files.ReadWrite%20offline_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. Refresh tokens apply to delegated flows, such as the authorization code flow. They do not apply to client credentials authentication, which obtains an app-only token directly using the client ID and secret and does not return a refresh token.

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.

How to Get a OneDrive API Access Token

A OneDrive access token allows your application to make authenticated requests to Microsoft Graph.

For delegated access, the application redirects the user to Microsoft’s authorization endpoint.

After authentication and consent, Microsoft returns an authorization code to the registered redirect URI.

The application exchanges this code for an access token using the OAuth 2.0 token endpoint.

For confidential server applications running without an interactive user, Microsoft supports the client credentials flow using application permissions and administrator consent.

After obtaining an access token, include it in the Authorization header of each Microsoft Graph request.

Monitor token expiry and acquire a replacement token using the authentication flow appropriate to your application.

For most production implementations, Microsoft recommends supported authentication libraries such as MSAL rather than manually managing every OAuth request.

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 for 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

OneDrive Upload API: Small and Large Files

Microsoft Graph supports two common approaches to uploading files to OneDrive.

Direct file upload

For files up to 250 MB, applications can upload or replace file contents using a single PUT request. Use the PUT request shown in the Upload File section above.

PUT https://graph.microsoft.com/v1.0/me/drive/root:/report.pdf:/content
Authorization: Bearer {access_token}
Content-Type: application/pdf

{binary-file-content}  

Large-file upload using an upload session

For files larger than 250 MB, or files requiring resumable transfers, Microsoft Graph supports upload sessions.

First, create an upload session:

POST https://graph.microsoft.com/v1.0/me/drive/root:/large-report.zip:/createUploadSession
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  }
}

Microsoft Graph returns an upload URL. Your application then uploads the file in sequential byte ranges to that URL, following Microsoft’s upload-session requirements.

This approach is useful for large document transfers, media files and systems that must recover from interrupted connections.

For implementation details, see the Microsoft Graph upload session documentation.

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.

Useful Links

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

OneDrive API Errors and Troubleshooting

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.

Microsoft Graph recommends respecting the Retry-After response header when throttling occurs.

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 or consent for the resource it is trying to reach.

To fix it, check the scopes requested in your authorization request and the permissions granted in Microsoft Entra.

For the signed-in user’s own OneDrive files, Files.ReadWrite is often enough. Files.ReadWrite.All or SharePoint site permissions may be needed for other users’ drives, shared drives or SharePoint content, and your organization’s policies may require admin consent.

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 does not have the permissions or consent required for the resource you are accessing. For the signed-in user’s own files, Files.ReadWrite is often enough. Check the scopes you requested and whether your organization requires admin consent. Files.ReadWrite.All or SharePoint site permissions may be needed for other drives or shared content.

Does OneDrive have a REST API?

Yes. Developers can access OneDrive files and folders through Microsoft Graph REST APIs to upload, retrieve, update, move and delete files, subject to the required permissions.

Where can I find OneDrive API documentation?

Official OneDrive API documentation is available through Microsoft Graph documentation. It includes authentication, REST endpoints, permissions, SDKs and sample requests.

How can I validate OneDrive API access?

First, obtain a valid Microsoft Graph access token. Then call an endpoint such as /me/drive using delegated authentication. Verify the response and confirm that the required permissions have been granted.

Is there a Microsoft OneDrive SDK?

Yes. Microsoft Graph SDKs support multiple programming languages and help developers interact with OneDrive without manually constructing every REST request.