Skip to main content

OneDrive Integration

Want to put your cloud storage to work? Connect Microsoft OneDrive to SmythOS and let your agents manage files, list directories, and automate your document workflows in real time.

TL;DR

Link your Microsoft 365 Account to SmythOS via OAuth2. Register an application in Microsoft Entra to get a Client ID and Client Secret, then use our OneDrive components to empower agents to automate file and folder operations for users and groups.

List of OneDrive Components

Quickly compare OneDrive components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.

ComponentActionWhat it DoesInputsKey OutputsUse Case
List DrivesReadRetrieves all drives for a specific user.required userIddrivesFind all available drives for a user.
Get User OneDriveReadRetrieves a user's default OneDrive drive.required userIddriveIdGet the primary storage location for a user.
Get DriveReadRetrieves a specific drive by its unique ID.required driveIddriveId, nameVerify a specific drive exists before proceeding.
List Root ItemsReadFetches all files and folders in the root of a user's drive.required userIditemsGet a list of top-level folders and files.
Get Item by IDReadRetrieves a file or folder using its unique item ID.required userId, itemIditemId, webUrlAccess a specific, known file or folder.
Get Item by PathReadRetrieves a file or folder using its relative path.required userId, item-pathitemId, webUrlAccess a file when you know its path but not its ID.
List Drive Item ChildrenReadRetrieves the contents (files/folders) of a specific folder.required userId, itemIdchildrenList all files within a specific project folder.
List Group DrivesReadRetrieves all drives associated with a specific Microsoft 365 Group.required groupIddrivesFind all shared libraries for a specific team.
Get Group's Document LibraryReadRetrieves the default document library (drive) for a group.required groupIddriveIdAccess a team's primary shared document space.
Get Group's Item By IDReadRetrieves a specific file/folder from a group drive by its ID.required groupId, itemIditemId, webUrlAccess a specific file in a shared team folder.
Get Group's Item By PathReadRetrieves a specific file/folder from a group drive by its path.required groupId, item-pathitemId, webUrlAccess a shared file using its known path.
List Group's Item ChildrenReadRetrieves the contents of a folder within a group drive.required groupId, itemIdchildrenList all documents in a shared project directory.
INFO
Why Integrate OneDrive with Your Agent?

Microsoft OneDrive is a cornerstone of modern document management. Integrating it with SmythOS unlocks powerful automation capabilities:

  • Automated File Organization: Agents can automatically create folders, move files, and maintain a structured directory for projects, reports, or client records.
  • Seamless Collaboration: Programmatically manage file sharing and permissions to ensure team members always have access to the latest documents.
  • Centralized Data Hub: Use OneDrive as the single source of truth for documents generated or processed by your agents, from invoices to analytical reports.
  • Enhanced Productivity: Eliminate manual file handling by letting agents fetch, update, and manage your cloud storage, freeing up your team to focus on higher-value work.

Prerequisites

Before you begin, please ensure you have the following:

  • An active SmythOS account. (Sign up here).
  • A Microsoft 365 Account with administrative permissions to register applications in Microsoft Entra.
  • Necessary permissions (e.g., Files.ReadWrite.All, Group.Read.All) granted to your application in Microsoft Entra.

Getting Started With OneDrive

Authentication is handled via OAuth2, which requires you to register an application within the Microsoft Entra portal. This is a one-time setup.

Step 1: Register an Application in Microsoft Entra

  1. Navigate to the Microsoft Entra Portal.
  2. Go to Identity > Applications > App registrations and click + New registration.
  3. Configure your application:
    • Name: Give it a descriptive name (e.g., "SmythOS OneDrive Integration").
    • Supported account types: Choose the option that best fits your organization's needs.
    • Redirect URI: Select Web from the dropdown and enter https://app.smythos.com/oauth/oauth2/callback.
  4. Click Register.

Step 2: Obtain Client ID and Client Secret

  1. Client ID: From your new application's Overview page, copy the Application (client) ID. This is your Client ID.
  2. Client Secret:
    • In your application's menu, navigate to Certificates & secrets.
    • Under the Client secrets tab, click + New client secret.
    • Add a description, choose an expiration period, and click Add.
    • Immediately copy the Value of the new secret. This is your Client Secret and it will be hidden after you leave this page.

Step 3: Configure API Permissions

  1. In your app registration menu, go to API permissions.
  2. Click + Add a permission, select Microsoft Graph, and choose Delegated permissions.
  3. Search for and add the necessary permissions for the components you intend to use. Common permissions include:
    • Files.ReadWrite.All
    • Sites.Read.All
    • User.Read
    • Group.Read.All
  4. Click Add permissions. If prompted, click the Grant admin consent for [Your Directory] button to finalize permissions.

Step 4: Authenticate in SmythOS

  1. In your SmythOS agent graph, drag any OneDrive component onto the canvas.
  2. Click the component to open its Settings panel.
  3. Enter the Client ID and Client Secret you obtained. For best security practices, store these credentials in the SmythOS Vault and reference them here.
  4. Click the blue Authenticate button. You will be redirected to a Microsoft sign-in page to authorize the connection.
Heads-up
Once you authenticate, the connection is saved for your SmythOS account. You won't need to re-enter credentials for other OneDrive components. Use the Sign Out button in the component settings if you need to switch accounts or re-authenticate.

Which OneDrive Component Should I Use?

If you need to…TargetUse this ComponentWhy this one?
List all files in a personal folderA user's folder IDList Drive Item ChildrenDirectly retrieves contents of a known folder.
Get a specific file by pathA known file pathGet Item by PathEasiest way to access a file without knowing its ID.
List all drives for a teamA group IDList Group DrivesShows all SharePoint libraries associated with a team.
Find a team's main folderA group IDGet Group's Document LibraryDirectly accesses the primary shared drive for a group.
Get a user's main driveA user IDGet User OneDriveThe simplest way to get to a user's personal OneDrive.

Component Details

This section provides detailed information for each OneDrive component.

List Drives

Retrieves a list of all drives (both personal OneDrive and SharePoint document libraries) that a user has access to.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
userIdrequiredThe unique ID of the user whose drives you want to list.

Outputs

FieldDescription
drivesAn array of drive objects associated with the user.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Determine which SharePoint sites a user is a member of by listing all their available drives.

{
"component": "onedrive.listDrives",
"userId": "user-guid-from-entra"
}
Troubleshooting

If the drives array is empty, ensure the user has access to at least one drive and that your app has Sites.Read.All permissions.

Get User OneDrive

Retrieves the user's default OneDrive drive, which is their personal cloud storage.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
userIdrequiredThe ID of the user whose default OneDrive you want to retrieve.

Outputs

FieldDescription
driveIdThe unique ID of the user's default OneDrive.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Get the driveId for a user's personal OneDrive to use in subsequent steps, like listing root items or creating folders.

{
"component": "onedrive.getUserOneDrive",
"userId": "user-guid-from-entra"
}
Troubleshooting

A 404 Not Found error can occur if the user does not have a OneDrive provisioned for their account.

Get Drive

Retrieves a specific drive by its unique ID. This is useful for accessing both personal drives and SharePoint document libraries.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
driveIdrequiredThe unique ID of the drive to retrieve.

Outputs

FieldDescription
driveIdThe ID of the retrieved drive.
nameThe name of the retrieved drive.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

After listing all of a user's drives, use this component with a specific driveId to verify its name before performing further actions.

{
"component": "onedrive.getDrive",
"driveId": "drive-id-from-previous-step"
}
Troubleshooting

A 404 Not Found error indicates an invalid driveId or that the authenticated user lacks permission to access it.

List Root Items

Fetches the collection of files and folders in the root directory of a user's default OneDrive.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
userIdrequiredThe ID of the user whose root items you want to list.

Outputs

FieldDescription
itemsAn array of item objects (files and folders) in the root.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

An agent needs to check for a specific configuration file or a "Reports" folder in the top level of a user's OneDrive.

{
"component": "onedrive.listRootItems",
"userId": "user-guid-from-entra"
}
Troubleshooting

Ensure your app has at least Files.Read.All permission. If the items list is unexpectedly empty, verify files exist in the root of the user's drive.

Get Item by ID

Retrieves a file or folder from a user's drive using its unique item ID.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
userIdrequiredThe ID of the user who owns the item.
itemIdrequiredThe unique ID of the item to retrieve.

Outputs

FieldDescription
itemIdThe ID of the retrieved item.
nameThe name of the retrieved item.
webUrlThe web URL to access the item.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Access a specific, known file or folder when you have its ID from a previous step, such as listing a folder's children.

{
"component": "onedrive.getItemById",
"userId": "user-guid-from-entra",
"itemId": "item-id-from-previous-step"
}
Troubleshooting

A 404 Not Found error means the itemId is incorrect or does not belong to the specified userId.

Get Item by Path

Retrieves a file or folder from a user's drive using its relative path from the root.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
userIdrequiredThe ID of the user who owns the item.
item-pathrequiredThe path of the item, e.g., /Documents/Report.docx.

Outputs

FieldDescription
itemIdThe ID of the retrieved item.
nameThe name of the retrieved item.
webUrlThe web URL to access the item.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Access a file when you know its location and name but not its ID, such as fetching /Attachments/invoice.pdf.

{
"component": "onedrive.getItemByPath",
"userId": "user-guid-from-entra",
"item-path": "/Documents/Q3-Report.docx"
}
Troubleshooting

The path must be URL-encoded and start with a /. A 404 Not Found error indicates the path is incorrect.

List Drive Item Children

Retrieves the contents (files and folders) of a specific folder by its item ID.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
userIdrequiredThe ID of the user who owns the parent item.
itemIdrequiredThe ID of the folder whose children you want to list.

Outputs

FieldDescription
childrenAn array of item objects representing the folder's contents.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

After finding a "Project Alpha" folder, use this component to list all the documents inside it to process them one by one.

{
"component": "onedrive.listDriveItemChildren",
"userId": "user-guid-from-entra",
"itemId": "folder-item-id-from-previous-step"
}
Troubleshooting

A 404 Not Found error means the itemId is incorrect or the item is a file, not a folder.

List Group Drives

Retrieves all drives (SharePoint document libraries) associated with a specific Microsoft 365 Group.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
groupIdrequiredThe ID of the group whose drives you want to list.

Outputs

FieldDescription
drivesAn array of drive objects associated with the group.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Find all shared libraries for the "Marketing Team" group to search for assets across all their document repositories.

{
"component": "onedrive.listGroupDrives",
"groupId": "group-guid-from-entra"
}
Troubleshooting

Requires Group.Read.All and Sites.Read.All permissions. An empty response may mean the group has no SharePoint sites.

Get Group's Document Library

Retrieves the default document library (drive) for a given Microsoft 365 Group.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
groupIdrequiredThe ID of the group whose document library you want to retrieve.

Outputs

FieldDescription
driveIdThe ID of the group's default drive.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Directly access a team's primary shared folder, often named "Documents," without needing to list all their drives first.

{
"component": "onedrive.getGroupDocumentLibrary",
"groupId": "group-guid-from-entra"
}
Troubleshooting

A 404 Not Found error can occur if the groupId is invalid or the group does not have a provisioned document library.

Get Group's Item By ID

Retrieve a specific item from a group's drive by ID.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
groupIdrequiredThe ID of the group.
itemIdrequiredThe ID of the item to retrieve.

Outputs

FieldDescription
itemIdThe ID of the retrieved item.
nameThe name of the retrieved item.
webUrlThe web URL to access the item.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Access a specific file in a shared team folder when you have its unique ID.

{
"component": "onedrive.getGroupItemById",
"groupId": "group-guid-from-entra",
"itemId": "item-id-from-group-drive"
}
Troubleshooting

Ensure the itemId corresponds to an item within one of the specified group's drives.

Get Group's Item By Path

Retrieve a group's OneDrive item by its path within the group's default document library.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
groupIdrequiredThe ID of the group.
item-pathrequiredThe relative path of the item from the root of the default document library.

Outputs

FieldDescription
itemIdThe ID of the retrieved item.
nameThe name of the retrieved item.
webUrlThe web URL to access the item.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

Fetch a shared team document like /General/Project-Plan.xlsx when you know its path.

{
"component": "onedrive.getGroupItemByPath",
"groupId": "group-guid-from-entra",
"item-path": "/Shared Documents/Q3-Marketing-Plan.pptx"
}
Troubleshooting

The path must be relative to the group's default document library root. A 404 Not Found error means the path is incorrect.

List Group's Item Children

Retrieve the children of an item within a group's drive.

INFO
This component uses a standard OAuth2 authentication flow detailed in the Getting Started section.

Inputs

FieldRequiredNotes
groupIdrequiredThe ID of the group.
itemIdrequiredThe ID of the parent folder in the group drive.

Outputs

FieldDescription
childrenAn array of item objects in the folder.
responseThe raw JSON response from the OneDrive API.
headersHTTP headers from the API response.
Use Case

List all proposals located in the /Proposals/2025/ folder within a sales team's shared drive.

{
"component": "onedrive.listGroupItemChildren",
"groupId": "group-guid-from-entra",
"itemId": "group-folder-item-id"
}
Troubleshooting

A 404 Not Found error can occur if the itemId does not belong to the specified groupId or is not a folder.

Best Practices & Advanced Tips

  • Use the SmythOS Vault: Never hardcode your Client ID or Client Secret directly in your components. Always store them securely in the SmythOS Vault and reference them.
  • Principle of Least Privilege: In the Microsoft Entra portal, only grant the API permissions that your agent absolutely needs to function. Avoid overly broad permissions like Files.ReadWrite.All if your agent only needs to read files.
  • Manage IDs Dynamically: Chain components together. Use the driveId or itemId from the output of one component as the input for another. This makes your workflows robust and adaptable.
  • Error Handling: Always check the response output for error codes or messages. Build conditional logic in your agent to handle potential failures gracefully, such as by sending a notification or retrying the operation.
  • Group vs. User Components: Be mindful of which components you are using. Operations on shared team libraries require the "Group" components and a groupId, while personal files use the standard user components and a userId.

Troubleshooting Common Issues

  • Error: 403 Forbidden or PERMISSION_DENIED

    • Cause: The application is missing the required API permissions in Microsoft Entra, or admin consent has not been granted.
    • Solution: Go to your app registration's API permissions page. Verify that you have added and granted admin consent for all necessary permissions (e.g., Files.ReadWrite.All, Sites.Read.All).
  • Error: 404 Not Found

    • Cause: The userId, groupId, driveId, or itemId is incorrect. It could also be that the path in a Get Item by Path component is wrong.
    • Solution: Double-check all IDs being passed into the component. Ensure they are correct and that the authenticated user has access. For path-based lookups, verify the full path is correct and URL-encoded.
  • Error: 401 Unauthorized or Authentication Issues

    • Cause: The Client ID or Client Secret is incorrect, or the OAuth token has expired.
    • Solution:
      1. Verify that the Client ID and Client Secret in the component settings match the values in Microsoft Entra.
      2. Use the Sign Out button in the component settings, then click Authenticate again to refresh the connection and obtain a new token.

What's Next?

You are now ready to build powerful automations with the SmythOS OneDrive Integration!

Consider these ideas:

  • Build an Agent That...

    • Automatically saves email attachments to a specific "Attachments" folder in your personal OneDrive.
    • Watches a "New Invoices" folder in a team's shared drive and, upon detecting a new file, processes it and sends a notification to the finance channel in Slack.
    • Generates a monthly report, saves it as a PDF, and uploads it to a "Monthly Reports" folder in a SharePoint document library.
  • Explore Other Integrations: Combine OneDrive with other SmythOS connectors. For example, use the Google Sheets Integration to read data for a report, then use OneDrive components to save the final document.