OneDrive Enterprise Collection

OneDrive Enterprise Collection Integration with Onna

Overview

This guide explains how to set up and interact with a Microsoft OneDrive Enterprise collection through the Onna Platform API. You'll learn how to create a workspace and collection, authorize access to Microsoft 365 via OAuth2, list users and their OneDrive folders, configure sync filters to control exactly which users and folders are synchronized, start the sync, and clean up your environment afterward.

For a full reference of every sync filter field, see the Sync Filters Configuration Guide.

Create a workspace

A workspace is the main container for your project in Onna. Create one with a POST request.

curl --location --request POST 'https://api.onna.com/v1/workspaces' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My New Workspace",
  "description": "This is a workspace for organizing OneDrive data in Onna."
}'

Where:

• name is the name of the workspace.
• description is a brief description of the workspace's purpose.

A successful response (201) will return:

{
  "onna_id": "<WORKSPACE_ID>"
}

Create a OneDrive Enterprise Collection

Next, create a OneDrive Enterprise collection within the workspace you created. The collection is the container for the users and folders you will sync from Microsoft 365 OneDrive.

curl --location --request POST 'https://api.onna.com/v1/collections' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My OneDrive Enterprise Collection",
  "onna_parent_id": "<WORKSPACE_ID>",
  "type": "eonedrive",
  "credential_id": "<WALLET_ID>"
}'

Where:

• name is the name of the collection.
• onna_parent_id is the ID of the workspace that this collection will belong to.
• type is the type of collection being created. For Microsoft OneDrive Enterprise, the type is eonedrive.
• credential_id is the ID of the wallet containing credentials for the Microsoft 365 service.

A successful response (201) will return:

{
  "onna_id": "<COLLECTION_ID>",
  "type": "eonedrive"
}

Actionable Tips: While creating collections, consider adding metadata that might be required later for reporting or analysis.

You might also want to implement a naming convention (like Collection-{WorkspaceName}-OneDrive) for better organization.

Initiate OAuth2 Flow to Get an Authorization Code

To authorize access to the Microsoft 365 tenant, initiate the OAuth2 flow. It will return an authorization URL. Open this URL in your browser to log in and grant the application access to OneDrive.

curl --location --request GET 'https://api.onna.com/v1/collections/authorization_url/eonedrive?redirect_to=http%3A%2F%2Flocalhost%3A9000%2Fcallback' \
--header 'Authorization: Bearer <token>'

Once you've authorized, you'll be redirected to the provided redirect_to URL with an authorization code.

Use a temporary redirect URI during development (like http://localhost:9000/callback) for easier testing. Be sure to change this to a production-ready URL before going live.

Pair the Authorization Code with the Collection (Token Exchange)

After successful authorization, exchange the authorization code for an access token bound to the collection.

curl --location --request POST 'https://api.onna.com/v1/collections/<COLLECTION_ID>/pair_credentials?auth_code=<AUTH_CODE>' \
--header 'Authorization: Bearer <token>'

Where:

• auth_code is the authorization code you received during the authorization process.

A successful response returns 204 No Content.

Retrieve the List of Users

To retrieve the users available in the authorized Microsoft 365 tenant, send a GET request to the collection's /users endpoint.

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/users' \
--header 'Authorization: Bearer <token>'

Example user response:

{
  "entries": [
    {
      "id": "f8a9c3b1-1234-4abc-9def-0987654321ab",
      "display_name": "Lisa Simpson",
      "mail": "lisa@onnaqa.com",
      "user_principal_name": "lisa@onnaqa.com",
      "job_title": "Data Analyst",
      "department": "Engineering",
      "office_location": "Springfield"
    },
    {
      "id": "d4c7b8e2-5678-4fff-aaaa-1122334455cc",
      "display_name": "Bart Simpson",
      "mail": "bart@onnaqa.com",
      "user_principal_name": "bart@onnaqa.com",
      "job_title": "Developer",
      "department": "Engineering",
      "office_location": "Springfield"
    }
  ],
  "limit": 1000,
  "next_marker": "<next_marker>"
}

Where:

• id is the unique identifier of the user. Use this value in the selected or excluded arrays when configuring sync filters.
• display_name is the user's full name.
• mail is the user's primary email address.
• user_principal_name is the user's login name (UPN), typically the same as mail.

Retrieve the List of Folders for a User

To retrieve the OneDrive folders for a specific user, send a GET request to the collection's /folders endpoint. Pass the user's id as a query parameter.

curl --location --request GET 'https://api.onna.com/v1/collections/<COLLECTION_ID>/folders?user_id=<USER_ID>' \
--header 'Authorization: Bearer <token>'

Example folder response:

{
  "results": [
    {
      "id": "01BYE5RZ5NQXWVBK2MXNBJIQN4FKDRFH55",
      "name": "Documents",
      "link": "https://onnaqa-my.sharepoint.com/personal/lisa_onnaqa_com/Documents/Forms/AllItems.aspx",
      "size": 102400,
      "created_datetime": "2023-01-15T10:30:00Z",
      "last_modified_datetime": "2024-09-10T08:00:00Z",
      "sorted_path_elements": [
        { "id": "root", "name": "OneDrive" },
        { "id": "01BYE5RZ5NQXWVBK2MXNBJIQN4FKDRFH55", "name": "Documents" }
      ]
    },
    {
      "id": "01BYE5RZ6PLYPWCL3MXEABK2M3FGSJ2U56",
      "name": "Pictures",
      "link": "https://onnaqa-my.sharepoint.com/personal/lisa_onnaqa_com/Documents/Pictures",
      "size": 51200,
      "created_datetime": "2023-02-01T09:00:00Z",
      "last_modified_datetime": "2024-08-20T14:00:00Z",
      "sorted_path_elements": [
        { "id": "root", "name": "OneDrive" },
        { "id": "01BYE5RZ6PLYPWCL3MXEABK2M3FGSJ2U56", "name": "Pictures" }
      ]
    }
  ],
  "total_count_label": "2 folders",
  "_next": null
}

Where:

• id is the folder identifier.
• name is the folder name (for example, Documents, Pictures, Desktop).
• link is the direct URL to the folder in SharePoint/OneDrive.
• sorted_path_elements is the ordered list of path components from the drive root to this folder.

Configure Sync Filters

Sync filters control which users and folders are synchronized. OneDrive Enterprise sync filters use per-user keys (the user's id from the /users endpoint) to control which folders are synchronized for each user.

Update the collection with the selected configuration by sending a PATCH request.

Sync all folders for a specific user

Use the user's id as the top-level key in sync_filters and set all_selected to true to sync all of their OneDrive folders.

curl --location --request PATCH 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "sync_status": "pending",
  "sync_filters": {
    "f8a9c3b1-1234-4abc-9def-0987654321ab": {
      "all_selected": true,
      "selected": [],
      "excluded": [],
      "filter_type": "user_folders",
      "filter_name": "User onedrive"
    }
  }
}'

Sync specific folders for a user

Set all_selected to false and list the folder IDs to include in selected.

curl --location --request PATCH 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "sync_status": "pending",
  "sync_filters": {
    "f8a9c3b1-1234-4abc-9def-0987654321ab": {
      "all_selected": false,
      "selected": [
        { "id": "01BYE5RZ5NQXWVBK2MXNBJIQN4FKDRFH55" },
        { "id": "01BYE5RZ6PLYPWCL3MXEABK2M3FGSJ2U56" }
      ],
      "excluded": [],
      "filter_type": "user_folders",
      "filter_name": "User onedrive"
    }
  }
}'

Sync multiple users with different folder selections

Add multiple per-user keys to configure folder selection independently for each user.

curl --location --request PATCH 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "sync_status": "pending",
  "sync_filters": {
    "f8a9c3b1-1234-4abc-9def-0987654321ab": {
      "all_selected": false,
      "selected": [
        { "id": "01BYE5RZ5NQXWVBK2MXNBJIQN4FKDRFH55" }
      ],
      "excluded": [],
      "filter_type": "user_folders",
      "filter_name": "User onedrive"
    },
    "d4c7b8e2-5678-4fff-aaaa-1122334455cc": {
      "all_selected": true,
      "selected": [],
      "excluded": [],
      "filter_type": "user_folders",
      "filter_name": "User onedrive"
    }
  }
}'

Where:

• Each top-level key in sync_filters is a user's id from the /users endpoint.
• The id values in the selected array are folder IDs from the /folders endpoint.
• Use all_selected: true with an empty selected array to sync all folders for a user.

Filter fields

The top-level request fields are the same as any collection update:

Field	Type	Description
sync_status	String	Sync lifecycle state. Set to "pending" to queue a sync after filters are saved.
sync_filters	Object	OneDrive Enterprise sync filter configuration (see below).
type_sync	String	Sync type. Supported values: "one", "arch", "auto".

The sync_filters object contains per-user keys where each key is the user's id from the /users endpoint:

Per-user key (keyed by user id):

Field	Type	Description
all_selected	Boolean	If true, all folders for the user are synchronized. When false, only the folders listed in selected are included.
selected	Array	Folders to include when all_selected is false. Each entry is { "id": "<folder_id>" }. Use the folder id from the /folders endpoint.
excluded	Array	Folders to exclude when all_selected is true. Each entry is { "id": "<folder_id>" }.
filter_type	String	Must be "user_folders".
filter_name	String	Display name for the filter (for example, "User onedrive").

A successful PATCH returns 204 No Content, indicating the filter configuration was saved.

Update Existing Filters

To change an existing filter configuration (for example, to add more users or folders), issue another PATCH to the same collection endpoint with the full updated sync_filters object. The new value replaces the previous one.

curl --location --request PATCH 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "sync_status": "pending",
  "sync_filters": {
    "f8a9c3b1-1234-4abc-9def-0987654321ab": {
      "all_selected": false,
      "selected": [
        { "id": "01BYE5RZ5NQXWVBK2MXNBJIQN4FKDRFH55" },
        { "id": "01BYE5RZ6PLYPWCL3MXEABK2M3FGSJ2U56" },
        { "id": "01BYE5RZ7QMZPXCL3MXEABK2M3FGSJ9X99" }
      ],
      "excluded": [],
      "filter_type": "user_folders",
      "filter_name": "User onedrive"
    }
  }
}'

Always send the complete sync_filters object on update. Fields that are omitted are treated as removed, not merged with the previous value.

Start the Sync

Once the filters are saved, initiate the sync process.

curl --location --request POST 'https://api.onna.com/v1/collections/<COLLECTION_ID>/start' \
--header 'Authorization: Bearer <token>'

A successful response (HTTP status code 200) indicates that the sync process has begun. Only the users and folders allowed by the configured filters are pulled into the collection.

Simulate Token Expiry and Refresh the Token

If the access token expires, you can refresh it by using the refresh token.

curl --location --request POST 'https://api.onna.com/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=<refresh_token>'

This will return a new access_token and refresh_token.

{
  "access_token": "<new_access_token>",
  "token_type": "bearer",
  "expires_in": 86399
}

Clean Up

Once you are done, you can clean up by deleting both the collection and the workspace.

curl --location --request DELETE 'https://api.onna.com/v1/collections/<COLLECTION_ID>' \
--header 'Authorization: Bearer <token>'

curl --location --request DELETE 'https://api.onna.com/v1/workspaces/<WORKSPACE_ID>' \
--header 'Authorization: Bearer <token>'

Note: Deleting a collection or workspace is permanent and cannot be undone.