Create integration

Create a Google Cloud Platform (GCP) integration with SuperAnnotate to add items from your GCP storage to SuperAnnotate. SuperAnnotate will have read-only access to your data; your items are stored in your storage and are only displayed in SuperAnnotate.

Step 1: Begin integration setup

1. Click on your Organization.
2. Go to the Integrations tab.
3. Click New Integration.
4. Select GCP.
5. In the Create GCP Integration pop-up, type the name of your integration under Integration name.
6. Under Team, you can add the integration to one or multiple teams (optional). The integration will be available in the selected team(s) only.

📘

It is also possible for Team Owners and Team Admins to set up an integration through the Team Setup tab.

🚧

Only Organization Owners can set up an integration from the Organization tab.

❗️

Please note that you can’t create an integration with a GCP bucket if it is empty. Make sure that you’ve uploaded items to it beforehand to avoid any errors.

Step 2: Bucket and annotation storage

1. On the setup page, type your GCP bucket name (max 120 characters).
2. Choose an Annotation location. This will decide where your annotation data will be stored:
   • SuperAnnotate - your annotation data will be stored on our servers.
   • GCP bucket - type in the location path where the annotations will be stored. SuperAnnotate requires read, write and delete access to the provided location.

📘

• Choosing an annotation location allows you to maintain an extra level of project privacy and security by ensuring that all annotation data will be stored in a location of your choice. If the provided location doesn’t exist, it will be created when you annotate an item from that bucket. The path to the annotated JSON file will be as follows: BUCKET_NAME / ANNOTATION_LOCATION / data / TEAM_ID / ANNOTATION_JSON.json
• Please note that if your annotation JSON file is too large, it’ll have to be temporarily downloaded and processed to make it available, then deleted after 24 hours. For video projects, this applies to files that exceed 5MB. For other project types, this applies to files that exceed 15MB.

📘

About the Read/Write/Delete access

The write and delete permissions are required during the integration setup process when users define their own cloud storage as the annotation storage location. For this setup, SuperAnnotate checks the connection to the bucket to ensure proper access. As part of this check, the platform creates a temporary file named checkConnection.json in the specified folder, and then immediately deletes it. This ensures that the write and delete operations are properly configured.

When assigning the Storage Object User role—which has the write and delete permissions

—users can apply an IAM condition to limit this permission to a specific folder within the GCP bucket. This allows users to define exactly where SuperAnnotate is allowed to write and delete files.

🚧

Future upload methods will be defined based on the annotation location type of the chosen integration. Learn more.

❗️

The Explore, Insights and Analytics features will be unavailable for any project that uses integrations whose annotations aren’t stored on SuperAnnotate’s servers.

Step 3: Create a service account

1. In GCP, go to IAM & Admin.
2. Go to Service Accounts.
3. Click Create Service Account.
4. Type in a name for your service account.
5. Skip the next steps and click Done.

Step 4: Grant permissions

Bucket

First, you must provide your bucket with the Storage Object Viewer role.

1. Click on the service account you created in Step 3.
2. Select and copy the Email provided under Service Account Details.
3. Go to your bucket and into the Permissions tab.
4. Click Grant Access.
5. Under Add Principals, paste the email into the field.
6. Under Assign roles, select Storage Object Viewer.
7. Click Save.

Annotation location

If you've selected your GCP bucket as your annotation location, then you must provide the Storage Object User to the specified path, depending on the privileges you want to provide your service account:

1. Click on the service account you created in Step 3.
2. Select and copy the Email provided under Service Account Details.
3. Go to your bucket and into the Permissions tab.
4. Click Grant Access.
5. Under Add Principals, paste the email into the field.
6. Under Assign roles, select Storage Object User.
7. Then, click + Add IAM condition.
8. Type in a title for this condition.
9. For the Condition type, click Resource and select Name.
10. For the Operator, select Starts with.
11. In the Value field, paste this path: projects/_/buckets/BUCKET_NAME/objects/FOLDER_1/FOLDER_2. Be sure to replace the BUCKET_NAME and FOLDER according to your bucket name and annotation folder name.
12. Click Save.

Step 5: Upload the service account’s key

1. Under your service account, go to the Keys tab.
2. Click Add Key and select Create New Key.
3. Make sure JSON is selected and click Create. This will download a JSON file.
4. Go back to SuperAnnotate’s integration setup page.
5. Upload the JSON file in the final step.
6. Click Create.

Validate Integration

To validate your GCP integration:

1. In Integrations, find your integration.
2. Click the three dots ⋮.
3. Select Check connection.

Edit team

If you need to make your integration available for more teams, or you want to revoke a team's access to it, you may edit the permissions accordingly.

To add or remove an integration to one or multiple teams:

1. In Integrations, find your integration.
2. Click the three dots ⋮.
3. Select Edit team.
4. Add one or multiple teams from the dropdown, or remove a team by clicking the X on their name. To add all teams, choose Select all. To remove all teams, click the X on the right side of the field.
5. Click Save.

Delete integration

To delete an integration:

1. In Integrations, find your integration.
2. Click the three dots ⋮.
3. Select Delete Integration.
4. In the popup, click Delete.

🚧

Please note that by deleting the integration, any items uploaded to your projects from this integration will no longer be accessible.

Add items with GCP integration

You can add items from your GCP bucket(s) to your projects (excluding Tiled Imagery).

1. In Data, click Add.
2. Select Upload Images, Upload Videos, or Upload Documents (depending on your project type).
3. Go to External Storage.
4. In Integrations, choose an integration (mandatory) and type a folder path (optional).
5. Click Upload.

🚧

Folder paths

• Note that when you type in a folder path, all items within that folder will be uploaded. You won't be able to select and choose specific files from the folder.
• SuperAnnotate supports a two-level folder structure. This means that you can have items and folders in a project, but you can’t create or upload subfolders. For example, let’s say you want to upload a folder from your cloud storage to the root folder of your project. If that folder has several items and a subfolder, the subfolder will be excluded. If you want to upload items from that subfolder, you’ll have to specify its location path: FOLDER 1 / SUBFOLDER

🚧

Enable CORS for Text Projects

You’ll need to enable CORS in your storage to be able to make use of your items in the Text Editor. Learn more.