# OneDrive — File Storage API: connection

> Canonical URL: https://developers.apideck.com/apis/file-storage/onedrive/connection

# How to connect to OneDrive

Connecting OneDrive is a single authorization in Apideck Vault: you sign in with your Microsoft
account, approve the requested permissions, and the connection is live. Nothing has to be
registered or built on your side. The application owner has already registered the Microsoft
Entra app, so what you are doing is authorizing that app to work with the files in your own
OneDrive.

Two things are worth knowing before you start. If you are connecting a work or school account,
your organisation may require an administrator to approve the app first. And once you are
connected, you can point the connection at a specific drive, which matters if your account has
access to more than one.

## Prerequisites

- A Microsoft account with OneDrive, either:
  - a **personal Microsoft account** (the OneDrive that comes with an Outlook.com or Hotmail
    account), or
  - a **work or school account** whose Microsoft 365 licence includes OneDrive. If OneDrive has
    never been opened for your account, open it once in a browser so Microsoft provisions the
    drive before you connect.
- Access to the files you intend to work with. The connection can only reach what your own
  account can reach.
- For a work or school account: **administrator approval, if your organisation requires it**. See
  [If your organisation requires administrator approval](#if-your-organisation-requires-administrator-approval)
  below.

## What the connection asks for

The Microsoft consent screen lists the permissions the application owner configured. By default
the connector requests:

| Permission | What it is used for |
|---|---|
| `Files.ReadWrite.All` | Reading and writing files and folders in the drives your account can access |
| `offline_access` | Keeping the connection alive so you are not asked to sign in again for every request |
| `openid` | Signing you in |

An application owner can narrow this to read-only access (`Files.Read.All`), in which case the
consent screen shows read permissions only. The name shown on the consent screen is the
application owner's own Microsoft Entra app, or "Apideck" when they are using Apideck's temporary
shared test credentials.

## Steps

1. In Vault, select the **OneDrive** connector.
2. Click **Authorize**. You are redirected to the Microsoft sign-in page at
   `login.microsoftonline.com`.
3. Sign in with the Microsoft account whose OneDrive you want to connect. **The account you sign
   in with decides which drive is connected**, so if you use more than one Microsoft account,
   check which one you are signed in as. Microsoft reuses an existing browser session, so use a
   private or incognito window if you were recently signed in as someone else.
4. Review the requested permissions and approve them. If you are signed in as an administrator,
   Microsoft may also offer to consent on behalf of your organisation: choosing that grants the
   permissions for the whole tenant, so colleagues connecting later are not prompted individually.
5. You are returned to Vault and the connection shows as connected.
6. Optionally set the **Drive** setting (see below), then save.

## Choosing a drive

The connection has one optional setting, **Drive**. Leave it alone and the connector uses your
account's default drive, which is what most consumers want.

The list is populated from your own account, so it only fills in **after** you have authorized:
open the connection settings again once the connection is live and the dropdown shows the drives
the connector can see, each labelled with its name and type, for example `My files (personal)`.
Pick one and save.

A connection is pinned to a single drive. If you need to work with more than one drive, for
example your own files plus a shared library your account has access to, create a separate
connection for each drive rather than switching the setting back and forth.

## If your organisation requires administrator approval

Microsoft lets every organisation decide whether ordinary users may approve an app for
themselves. Plenty of tenants switch that off, so the first person to connect sees a message that
an administrator has to approve the app instead of the normal consent screen. Most often that is a
policy in your own organisation. It can also come from how the application owner has set their
Microsoft app up for use outside their own organisation, which only they can change. So if nobody
in your organisation can connect at all, raise it with the application owner as well as with your
administrator: the block may be theirs to remove.

There are two ways through it, and both end with a working connection:

- **An administrator authorizes the connection in Vault.** The permissions are granted while they
  complete the flow, and the connection belongs to their account.
- **An administrator approves the app for the organisation in advance.** Microsoft's prompt can
  usually forward the request to them for you. Once they have approved it, any permitted user can
  complete the authorization in Vault normally, each connecting their own drive.

If you are not sure which applies, send your administrator the name of the app shown on the
Microsoft screen and ask them to approve it. If they want to review it first, Microsoft's
[admin consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent)
documentation covers what they are being asked to grant, and administrators can review or revoke
consent at any time in the [Microsoft Entra admin center](https://entra.microsoft.com) under
Enterprise applications.

## Notes

- **A connection that sits idle for 90 days has to be authorized again.** Microsoft expires a
  refresh token after 90 days without use, and this is not configurable by the application owner
  or by Apideck. Normal day-to-day use keeps the connection alive indefinitely, so this only
  affects connections that genuinely go unused for three months: reconnect in Vault and the
  connection resumes.
- **Changing your own Microsoft password does not break the connection**, but an administrator
  resetting your password does, and so does revoking your sign-in sessions or refresh tokens,
  revoking the app's consent, disabling the account, or an administrator removing the app from the
  tenant. In each case the fix is to authorize again.
- **The connection reflects your own access.** If a colleague shares a folder with you after you
  connected, it becomes reachable without reconnecting; if your access is removed, it disappears.

## Troubleshooting

| What you see | What it usually means and what to do |
|---|---|
| `OAuthCodeExchangeError` right after signing in | Most often the Microsoft account you signed in with has no OneDrive provisioned: a work or school account whose licence does not include OneDrive, or an account where OneDrive has never been opened. Sign in to OneDrive in a browser once, confirm the drive exists, then authorize again. If the account demonstrably has OneDrive, the application owner's credentials may be misconfigured: ask them to re-check them, or contact [Apideck Support](https://help.apideck.com/en/articles/7774658). |
| A message that an administrator has to approve the app, or `AADSTS90094` | Usually your organisation does not allow users to consent for themselves. If nobody in your organisation can connect, also tell the application owner, because it can instead be how their Microsoft app is configured for use outside their own organisation, which they can change. Follow [If your organisation requires administrator approval](#if-your-organisation-requires-administrator-approval). |
| `AADSTS65001`: the user or administrator has not consented | Consent has not been granted for these permissions on this account yet. Complete the consent prompt; if your organisation's policy does not let you consent for yourself, an administrator has to approve it, either during the authorization or in advance. |
| The authorization completes but the files are not the ones you expected | You signed in with a different Microsoft account, or the connection is pointed at another drive. Check the **Drive** setting first; if that is not it, sign out of Microsoft or retry in a private window and authorize with the intended account. |
| The **Drive** dropdown is empty or shows no options | It is populated from your account, so it stays empty until the connection is authorized and callable. Complete the authorization, reopen the connection settings, and the drives appear. |
| A connection that worked stops after a long quiet period | The refresh token expired after 90 days without use. Authorize the connection again in Vault. |
| Requests fail with a permission error on writes | The application owner configured read-only scopes, or your own account has read-only access to that drive or folder. Check your access in OneDrive first, then ask the application owner which permissions their app requests. |

Microsoft documents every `AADSTS` code in its
[authentication and authorization error codes reference](https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes).

If the connection still will not complete after the checks above, contact
[Apideck Support](https://help.apideck.com/en/articles/7774658) with the exact error message from
the Microsoft screen and the Microsoft account type you are using.


[API reference](https://developers.apideck.com/apis/file-storage/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/file-storage/coverage)