# OneDrive

Stack AI integrates with Microsoft OneDrive. Two authentication methods are supported: 

* **OAuth2 (delegated)** for user-account access
* **App API / Client Credentials (app-only)** for background services and automation

***

### Setup an OAuth2 Connection

This method authenticates as a specific user. The connection acts on behalf of the user who completes the OAuth flow, and only has access to files that user can see.

You can set up a connection at Connections > OneDrive > OAuth Connection

<figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FR0Sn54df3XDIBBI2FqyW%2Fimage.png?alt=media&#x26;token=d8b07ac8-87d7-4d6b-aa84-d2ba22ab2f5a" alt=""><figcaption></figcaption></figure>

***

### Set up an App API Connection

This method authenticates as the application itself, not as any user. It is used to connect to services accounts or perform background automation where no interactive login is possible. A **User Principal Name (UPN)** must be supplied to specify which user's OneDrive to access.

#### Step 1: Create an Azure App Registration

1. Go to [Azure Portal > App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and click **New registration**.
2. Set a name (e.g., `Stack AI OneDrive`).
3. Under **Supported account types**, choose the appropriate option:
   * **Single tenant** — only users in your Azure AD directory.
   * **Multitenant** — users in any Azure AD directory. Use `common` as the Tenant ID in Stack AI.
4. **Redirect URI** is not required.
5. Click **Register**.

#### Step 2: Create Client Credentials

1. In your app registration, go to **Certificates & secrets > Client secrets**.
2. Click **New client secret**, set a description and expiry, and click **Add**.
3. Copy the **Value** immediately. It is only shown once.

#### Step 3:  Configure API Permissions

Go to **API permissions > Add a permission > Microsoft Graph > Application permissions** and add the following:

<table><thead><tr><th width="197.48046875">Permission</th><th width="124.9375">Type</th><th>Purpose</th></tr></thead><tbody><tr><td><code>Files.Read.All</code></td><td>Application</td><td>Read all files in OneDrive across users</td></tr><tr><td><code>Files.ReadWrite.All</code></td><td>Application</td><td>Read and write all files across users (only needed if your workflow modifies files)</td></tr><tr><td><code>User.Read.All</code></td><td>Application</td><td>Read all users' full profiles (required to resolve the User Principal Name)</td></tr></tbody></table>

{% hint style="info" %}
Application permissions are more powerful than delegated permissions because they are not scoped to a single user. Always apply the [principle of least privilege](https://learn.microsoft.com/en-us/entra/identity-platform/secure-least-privileged-access) — only grant `ReadWrite` if your workflow needs to modify files.
{% endhint %}

After adding permissions, click **Grant admin consent**. Admin consent is **required** for all application permissions.

#### Step 4: Connect in Stack AI

In the Stack AI connector setup, provide:

<table><thead><tr><th width="210.328125">Field</th><th>Value</th></tr></thead><tbody><tr><td><strong>Client ID</strong></td><td>Application (client) ID from your app registration's <strong>Overview</strong> page</td></tr><tr><td><strong>Client Secret</strong></td><td>The client secret value</td></tr><tr><td><strong>Tenant ID</strong></td><td>Your Azure AD tenant ID</td></tr><tr><td><strong>User Principal Name</strong></td><td>The email/UPN of the OneDrive user to access (e.g., <code>user@yourdomain.com</code>)</td></tr></tbody></table>

***

### Troubleshooting

#### Admin consent not granted

Application permissions require admin consent before they work. If you see `403 Forbidden` or `insufficient_scope` errors, go to **API permissions** and click **Grant admin consent for \[your tenant]**.

#### Invalid Tenant ID for client credentials

The `common` Tenant ID is only valid for OAuth2 (delegated) flows. For client credentials (App API), you must provide your specific Azure AD Tenant ID (a UUID).

#### Token expired

OAuth2 tokens expire after \~1 hour. Stack AI automatically uses the refresh token to obtain a new access token. Ensure `offline_access` is included in your OAuth2 scopes so refresh tokens are issued.

#### Accessing files across users (App-Only)

With client credentials, you must specify a **User Principal Name** to scope access to a particular user's OneDrive. The app identity itself does not have a personal drive.