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.
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.
Component | Action | What it Does | Inputs | Key Outputs | Use Case |
---|
List Drives | Read | Retrieves all drives for a specific user. | required userId | drives | Find all available drives for a user. |
Get User OneDrive | Read | Retrieves a user's default OneDrive drive. | required userId | driveId | Get the primary storage location for a user. |
Get Drive | Read | Retrieves a specific drive by its unique ID. | required driveId | driveId , name | Verify a specific drive exists before proceeding. |
List Root Items | Read | Fetches all files and folders in the root of a user's drive. | required userId | items | Get a list of top-level folders and files. |
Get Item by ID | Read | Retrieves a file or folder using its unique item ID. | required userId , itemId | itemId , webUrl | Access a specific, known file or folder. |
Get Item by Path | Read | Retrieves a file or folder using its relative path. | required userId , item-path | itemId , webUrl | Access a file when you know its path but not its ID. |
List Drive Item Children | Read | Retrieves the contents (files/folders) of a specific folder. | required userId , itemId | children | List all files within a specific project folder. |
List Group Drives | Read | Retrieves all drives associated with a specific Microsoft 365 Group. | required groupId | drives | Find all shared libraries for a specific team. |
Get Group's Document Library | Read | Retrieves the default document library (drive) for a group. | required groupId | driveId | Access a team's primary shared document space. |
Get Group's Item By ID | Read | Retrieves a specific file/folder from a group drive by its ID. | required groupId , itemId | itemId , webUrl | Access a specific file in a shared team folder. |
Get Group's Item By Path | Read | Retrieves a specific file/folder from a group drive by its path. | required groupId , item-path | itemId , webUrl | Access a shared file using its known path. |
List Group's Item Children | Read | Retrieves the contents of a folder within a group drive. | required groupId , itemId | children | List all documents in a shared project directory. |
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
- Navigate to the Microsoft Entra Portal.
- Go to Identity > Applications > App registrations and click + New registration.
- 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
.
- Click Register.
Step 2: Obtain Client ID and Client Secret
- Client ID: From your new application's Overview page, copy the Application (client) ID. This is your
Client ID
.
- 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.
- In your app registration menu, go to API permissions.
- Click + Add a permission, select Microsoft Graph, and choose Delegated permissions.
- 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
- Click Add permissions. If prompted, click the Grant admin consent for [Your Directory] button to finalize permissions.
Step 4: Authenticate in SmythOS
- In your SmythOS agent graph, drag any OneDrive component onto the canvas.
- Click the component to open its Settings panel.
- Enter the
Client ID
and Client Secret
you obtained. For best security practices, store these credentials in the SmythOS Vault and reference them here.
- Click the blue Authenticate button. You will be redirected to a Microsoft sign-in page to authorize the connection.
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… | Target | Use this Component | Why this one? |
---|
List all files in a personal folder | A user's folder ID | List Drive Item Children | Directly retrieves contents of a known folder. |
Get a specific file by path | A known file path | Get Item by Path | Easiest way to access a file without knowing its ID. |
List all drives for a team | A group ID | List Group Drives | Shows all SharePoint libraries associated with a team. |
Find a team's main folder | A group ID | Get Group's Document Library | Directly accesses the primary shared drive for a group. |
Get a user's main drive | A user ID | Get User OneDrive | The 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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
userId | required | The unique ID of the user whose drives you want to list. |
Outputs
Field | Description |
---|
drives | An array of drive objects associated with the user. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
Determine which SharePoint sites a user is a member of by listing all their available drives.
{
"component": "onedrive.listDrives",
"userId": "user-guid-from-entra"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
userId | required | The ID of the user whose default OneDrive you want to retrieve. |
Outputs
Field | Description |
---|
driveId | The unique ID of the user's default OneDrive. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
driveId | required | The unique ID of the drive to retrieve. |
Outputs
Field | Description |
---|
driveId | The ID of the retrieved drive. |
name | The name of the retrieved drive. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
userId | required | The ID of the user whose root items you want to list. |
Outputs
Field | Description |
---|
items | An array of item objects (files and folders) in the root. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
userId | required | The ID of the user who owns the item. |
itemId | required | The unique ID of the item to retrieve. |
Outputs
Field | Description |
---|
itemId | The ID of the retrieved item. |
name | The name of the retrieved item. |
webUrl | The web URL to access the item. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
userId | required | The ID of the user who owns the item. |
item-path | required | The path of the item, e.g., /Documents/Report.docx . |
Outputs
Field | Description |
---|
itemId | The ID of the retrieved item. |
name | The name of the retrieved item. |
webUrl | The web URL to access the item. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
userId | required | The ID of the user who owns the parent item. |
itemId | required | The ID of the folder whose children you want to list. |
Outputs
Field | Description |
---|
children | An array of item objects representing the folder's contents. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
groupId | required | The ID of the group whose drives you want to list. |
Outputs
Field | Description |
---|
drives | An array of drive objects associated with the group. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
groupId | required | The ID of the group whose document library you want to retrieve. |
Outputs
Field | Description |
---|
driveId | The ID of the group's default drive. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
groupId | required | The ID of the group. |
itemId | required | The ID of the item to retrieve. |
Outputs
Field | Description |
---|
itemId | The ID of the retrieved item. |
name | The name of the retrieved item. |
webUrl | The web URL to access the item. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
groupId | required | The ID of the group. |
item-path | required | The relative path of the item from the root of the default document library. |
Outputs
Field | Description |
---|
itemId | The ID of the retrieved item. |
name | The name of the retrieved item. |
webUrl | The web URL to access the item. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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.
This component uses a standard OAuth2 authentication flow detailed in the
Getting Started section.
Field | Required | Notes |
---|
groupId | required | The ID of the group. |
itemId | required | The ID of the parent folder in the group drive. |
Outputs
Field | Description |
---|
children | An array of item objects in the folder. |
response | The raw JSON response from the OneDrive API. |
headers | HTTP headers from the API response. |
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"
}
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
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.