Skip to main content
This guide provides a complete set of step-by-step instructions for securely connecting your Google Cloud Storage (GCS) bucket to Labelbox. The process uses a dedicated service account to grant Labelbox delegated access to your data.

​
Prerequisites

Before you begin, please ensure you have the following:
  • Permissions to create service accounts and assign IAM roles in your Google Cloud Platform (GCP) project.
  • The name of the GCS bucket you want to connect.

​
Step 1: Create a custom service account in GCP

First, you will create a new service account in your GCP project that Labelbox will use to access your data.
  1. In the Google Cloud Console, navigate to IAM & Admin > Service Accounts.
  2. Click Create Service Account.
  3. Enter a Service account name (e.g., labelbox-integration-svc) and a brief description.
  4. Click Create and Continue. You do not need to grant this service account access to the project or grant users access to this service account in this step.
  5. Click Done.
  6. From the list of service accounts, copy the email address of the service account you just created. You will need it in the next steps.

​
Step 2: Assign IAM roles to the service account

Next, you need to grant the new service account the necessary permissions to read data from your GCS bucket and to create security tokens.

​
Part A: Grant access to the GCS bucket

  1. Navigate to your GCS bucket by going to Cloud Storage > Buckets.
  2. Select the bucket you want to connect and go to the Permissions tab.
  3. Click Grant Access.
  4. In the New principals field, paste the email address of the service account you created in Step 1.
  5. In the Assign roles dropdown, select the Storage Object Viewer role.
  6. Click Save.

​
Part B: Grant service account token creator role

  1. Navigate back to IAM & Admin > Service Accounts and select the service account you created.
  2. Go to the Permissions tab for that service account.
  3. Click Grant Access.
  4. In the New principals field, paste the same service account email address.
  5. In the Assign roles dropdown, select the Service Account Token Creator role.
  6. Click Save.

​
Step 3: Grant Labelbox access to your service account

Now, you will authorize the official Labelbox service account to act on behalf of the service account you created.
  1. Navigate back to IAM & Admin > Service Accounts and select the service account you created.
  2. Go to the Permissions tab for that service account.
  3. Click Grant Access.
  4. In the New principals field, paste the official Labelbox service account email: client-gcp-production@labelbox-prod.iam.gserviceaccount.com.
  5. In the Assign roles dropdown, select the Service Account Token Creator role.
  6. Click Save.

​
Step 4: Configure CORS on your GCS bucket

Your GCS bucket must be configured to allow cross-origin requests from the Labelbox application.
  1. Install the gcloud command-line tool if you haven’t already.
  2. Create a JSON file named cors.json and paste the following content into it:
[
  {
    "origin": ["https://app.labelbox.com"],
    "method": ["GET"],
    "responseHeader": ["Content-Type"],
    "maxAgeSeconds": 3600
  }
]
  1. Run the following gcloud command, replacing BUCKET_NAME with the name of your GCS bucket:
    gcloud storage buckets update gs://BUCKET_NAME --cors-file=cors.json

​
Step 5: Complete the integration in Labelbox

Finally, return to Labelbox to complete the integration setup.
  1. In Labelbox, navigate to Settings > Integrations and click New integration.
  2. Select Google Cloud Platform.
  3. On the integration page, provide the following details:
    • Integration Name: A descriptive name for your integration.
    • GCS Bucket Name: The name of your GCS bucket (e.g., my-bucket).
    • Service Account Email: The email address of the custom service account you created in Step 1.
  4. Click Save integration.
Labelbox will automatically validate the connection. Once validated, your integration is complete and you can begin creating datasets with your GCS data.

​
Step 6: Upload your data

Once the connection is successfully established, you can begin uploading your data to Labelbox.

Import image data

Import text data

Import document data

Import HTML data

Import video data

Import geospatial data

Import audio data

If a dataset is signed by a GCP IAM integration, Labelbox will attempt to sign all data rows with this integration. The queryParams contain signing information. The value of rowData for each Data Row will be updated as follows: <https://storage.googleapis.com/${bucket}/${key}?{queryParams}>
Only gsutil URIs are supportedPlease ensure that you are using gsutil URIs during data import (JSON file or Python SDK).Example gsutil URI: gs://gcs-lb-demo-bucket/test.png
You should now be set up with IAM delegated access. Labelbox will use the roles you assigned to securely access data from your GCS bucket.