Skip to main content

Box Collection

Box Collection Integration with Onna​

Overview​

This guide explains how to set up and interact with the Box collection API in Onna. You'll learn how to create workspaces and collections, authorize access via OAuth2, sync users and folders, and clean up your environment afterward.

Create a workspace​

A workspace is the main container for your project in Onna. You will first create a workspace using 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 data from 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 Collection​

Next, create a collection within the workspace you just created. A collection is used to store folders and user data.

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

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 Box, the type is ebox.

A successful response (201) will return:

{
  "onna_id": "<COLLECTION_ID>",
  "type": "BoxEDatasource"
}
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}-{Type})

for better organization.

Initiate OAuth2 Flow to Get an Authorization Code​

To authorize access to Box collections, initiate the OAuth2 flow. It will return an authorization URL. Open this URL in your browser to log in and authorize the application.

curl --location --request GET 'https://api.onna.com/v1/collections/authorization_url/ebox?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. But, be sure to change this to a production-ready URL in the future.

Pair the Authorization Code with the Collection (Token Exchange)​

After successful authorization, you will receive an authorization code. Now, exchange this code for an access token.

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

Where:

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

Retrieve the List of Users and Folders​

To retrieve users and folders within the authorized collection, send a GET request:

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

The response includes a paginated list of users associated with the collection.

Example user data response:

{
  "entries": [
    {
      "type": "user",
      "id": "15523277032",
      "name": "Lisa Simpson",
      "login": "lisa@onnaqa.com",
      "role": "user",
      "status": "active",
      "modified_at": "2024-09-09T08:47:28-07:00"
    },
    {
      "type": "user",
      "id": "16871912359",
      "name": "Bart Simpson",
      "login": "bart@onnaqa.com",
      "role": "user",
      "status": "active",
      "modified_at": "2024-09-08T19:31:10-07:00"
    }
  ],
  "limit": 1000,
  "next_marker": "<next_marker>"
}

Where:

  • user_id is the ID of the user whose folders you want to retrieve.

Add Users and Folders to the Collection​

Now, you can add users and their folders to the collection. This is done by updating the collection with the selected user folder IDs.

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": {
    "<user_id_1>": {
      "all_selected": false,
      "selected": [
        { "id": "<folder_id_1>" },
        { "id": "<folder_id_2>" }
      ],
      "excluded": [],
      "filter_type": "user_folders",
      "filter_name": "User folders"
    }
  }
}'

Where:

  • sync_status: Indicates the sync status. "pending" means the sync is waiting to be started.
  • sync_filters: Defines the folders to include or exclude for each user. Each user is identified by their user ID.
    • all_selected: If true, all folders for the user are selected. In this case, it's set to false, meaning only the specified folders are selected.
    • selected: List of folder IDs to be included in the sync for each user.
    • excluded: List of folders to be excluded from the sync. In this case it is empty ([]), meaning no folders are excluded.
    • filter_type: Specifies the filter type. In this case, it's set to "user_folders", indicating user-specific folders.
    • filter_name: A descriptive name for the filter, "User folders" in this case.

Start the Sync​

Once you have added the users and folders, initiate the sync process.

curl --location --request POST 'https://api.onna.com/v1/collections/<collection_id>/start' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json'

A successful response (HTTP status code 200) indicates that the sync process has begun.

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 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.

Last updated on