To integrate cloud storage into your Labelbox workflows, set up an integration with your cloud provider. This involves using identity and access management (IAM) to delegate access to Labelbox. Here, we describe the general concepts, show related tasks, and point to instructions for supported providers. To use the Labelbox app to view or update cloud integrations:
  1. Sign in to the Labelbox app and then select Workspace Settings from the main menu.
  2. Select the Integrations tab.
2736

​
How IAM delegated access works

You will need to set up an IAM role in your cloud provider’s account and grant Labelbox the ability to assume that role in order to perform certain tasks on your behalf. Then, you create a policy that defines exactly what that assumed role can do. For example, Labelbox needs to be able to access assets stored in your AWS S3 bucket that you would like to label. So, you would grant the role the ability to perform GetObject requests on a particular S3 bucket (the setup instructions below will explain how to do this).

Delegated Access setup in AWS (similar in GCP)

IAM delegated access is highly flexible and allows you to control access at the granularity that you desire. You can grant Labelbox access to all of your buckets, a single bucket, or even a particular path within a bucket. You can even set up different integrations within Labelbox for different datasets or projects. IAM delegated access allows you to use private cloud-hosted buckets with Labelbox, which helps to ensure that your assets are kept safe.

​
When, why, and how Labelbox accesses your data

The Labelbox app will access assets for display in the user interface (e.g., during a labeling workflow, label review, when configuring a dataset, etc). When the Labelbox app needs access to an asset, it will request an expiring, signed URL from the Labelbox API (the backend). The backend will assume the role that you configured in your AWS account and generate a signed URL for the asset being requested. The URL will then be returned to the frontend, which will use it to access the asset directly from your cloud storage:

IAM Delegated Access client request flow

The Labelbox backend also needs access to assets in order to extract metadata (e.g., image and video dimensions, video codec and length, etc.), generate thumbnails, and more advanced tools. The backend similarly assumes the role that you configured, generates a temporary signed URL, and then uses that URL to access the asset. For example, the backend will download an asset, process it (e.g., media attribute extraction), and then release/delete it. Wherever possible, the asset will only be downloaded to memory and all processing will occur in memory. However, there may be cases where processing requires that the asset be written to a non-memory file system temporarily. In these cases, the asset will be written to some other ephemeral storage (such as a container’s file system) and deleted when processing completes.

Asset processing in the Labelbox backend

​
Data processing location

Currently, all asset processing is performed in US-based datacenters.

​
Set up integration

The setup instructions vary slightly based on the cloud storage solution. Choose the setup guide that corresponds to your cloud storage provider.
Cloud storage providerResource
Amazon S3Setup guide
Google cloud storageSetup guide
Microsoft azure blob storageSetup guide

​
Supported data types

Below are all of the asset types that you can import to Labelbox via IAM delegated access. Click on the links to see the import specifications for each data type. Note: you can also use IAM delegated access to add cloud-hosted attachments to your data rows.
Data typeSupported
ImagesImport specifications
VideoImport specifications
TextImport specifications
Tiled imagery (COG, NITF, GeoTIFF)Import specifications
AudioImport specifications
DocumentImport specifications
ConversationImport specifications

​
View all integrations

To access the integrations menu, go to the user menu > Workspace settings > Integrations tab. You can also access your workspace settings by clicking this link: https://app.labelbox.com/workspace-settings/integrations.

​
Select an integration when creating a dataset

If you create a dataset via the app UI, you will have the option to select an integration for the dataset. When following these steps, please ensure that you have selected the appropriate integration or the uploads will fail.
1

Go to Catalog.
2

Click New dataset.
3

Select a file to import.
4

Under Select Integration, choose an integration from the dropdown menu.

​
Note

When you create a new dataset through the UI that utilizes IAM delegated access, you will be prompted to select your integration before beginning the upload.

​
Update an integration

To update the integration linked to any dataset, regardless of how it was created, follow these steps:
1

Navigate to Catalog
2

Select the dataset where you want to update the integration
3

Click the dropdown next to the dataset name
4

Select the desired integration from the dropdown options

​
Admins only

Only Admins and Data admins can update integration settings on a dataset.

​
Select an integration in the SDK

When creating a dataset via the SDK, the create_dataset method has an optional iam_integration parameter that can be used to specify the desired integration. Sample code for viewing and selecting integrations, along with creating a dataset using this parameter, is shown in the Common SDK methods section below.

​
If no argument is provided to the optional iam_integration parameter in the create_dataset method, then the default integration will automatically be used.

​
SDK reference

For detailed Python SDK methods, checkout the reference

​
Delegated Access FAQ

Currently, the expiration time is set between 15 minutes to 24 hours depending on the selected cloud provider.
Yes, simply remove the “GetObject” permission from your AWS role’s permission policy and all active signed URLs will cease to have access to your S3 bucket.
Normally, Labelbox-hosted assets are served through a CDN to improve performance; however, Delegated Access assets are served directly from customer S3 buckets, so no CDN caching occurs.To control browser caching, you can configure various cache-related headers on your S3 bucket. See this link for details.
Yes, you might want to restrict access to your assets by only allowing requests from certain IP ranges. However, make sure to also grant the Labelbox backend access to your assets.
No, label annotations (e.g., image segmentation masks) are still stored in Labelbox-hosted storage, even when the underlying data row is customer-hosted.
It is possible to create multiple integrations. However, it is recommended to create only a single integration and make it the default. You can control what buckets to provide access to by configuring the IAM policy within the respective cloud provider.Every time you create a new dataset (via app or SDK), the Labelbox application will use the default IAM delegated access integration to access the content. This offers the best “set and forget” experience for customers who use Labelbox regularly.