Overview

Google Cloud Storage (GCS) is a scalable object storage service provided by Google Cloud. Bitmovin's Encoding API supports GCS buckets as an input source, allowing the encoder to read source media files stored in your buckets.

There are two authentication methods available when using GCS as a Bitmovin input:

• HMAC keys (legacy gcs resource type): uses an Access Key and Secret Key pair generated from a GCP user account. See Creating Access and Secret Keys for Google Cloud Storage for this approach.
• Service Account (gcs-service-account resource type): uses a GCP IAM Service Account and a JSON key file. This is the recommended approach, as it follows GCP security best practices, scopes permissions precisely to the bucket, and avoids tying credentials to a personal user account.

This guide covers the Service Account method.

Prerequisites

Before creating a Bitmovin GCS Service Account input, you need:

• An active Google Cloud project with billing enabled
• Permission to create and manage Service Accounts in GCP IAM

Step 1: Create a Service Account and Generate a JSON Key

1. In the Google Cloud Console, navigate to IAM & Admin → Service Accounts
2. Click Create Service Account, give it a descriptive name (e.g. bitmovin-encoding-input-service-account) and click Create and Continue
3. Skip the optional "Grant this service account access to project" step. You will grant access at the bucket level instead
4. Click Done
5. Click on your new Service Account and go to the Keys tab
6. Click Add Key → Create new key, select JSON, and click Create
7. The JSON key file containing your Service Account Credentials downloads automatically. Store it securely by following the Best practices for managing service account keys
8. Note the Service Account email address from the list, as you will need it in the next step

Step 2: Create a GCS Bucket and Grant Access

Granting access at the bucket level (rather than the project level) is both safer and does not require project-wide IAM admin permissions. For full details see Required Permissions for GCS Buckets for Encoding Input.

1. Navigate to Cloud Storage → Buckets and click Create
2. Enter a globally unique bucket name (e.g. bitmovin-encoding-input-bucket ). Note this down, as you will need it in the next step

⚠️

Avoid using underscore characters (_) in bucket names. While Google Cloud Storage allows underscores when creating a bucket, such buckets cannot be accessed using a standard URI string, which will cause the entire setup to fail.

3. Select a region appropriate for your workload
4. Configure the Access Control setting. Input buckets support both Public and Private access, as well as Uniform and Fine-Grained access control
5. Click Create
6. With your new bucket open, go to the Permissions tab and click Grant Access
7. In the New principals field, paste the Service Account email address noted before
8. Assign the Storage Object Viewer role (roles/storage.objectViewer). This grants the read access Bitmovin needs to download source files
9. Click Save

Step 3: Create a Bitmovin GCS Service Account Input

Note: The Bitmovin Dashboard does not support the gcs-service-account resource type. When creating a GCS output via the Dashboard, it uses the legacy HMAC-based gcs type, which asks for an Access Key and Secret Key. To use Service Account authentication, create the input via the API or an SDK as shown below.

You will need:

• A Bitmovin account and API key (Get started with the Bitmovin API)
• The JSON key file containing your Service Account Credentials (e.g, YOUR_JSON_SERVICE_ACCOUNT_CREDENTIALS.json)
• Your bucket name (e.g. bitmovin-encoding-input-bucket)

Use the Bitmovin API

Go to Create Service Account based GCS Input and fill in the required fields. Note that:

• X-Api-Key is your Bitmovin API Key
• serviceAccountCredentials is the entire content of your JSON key file
• bucketName is your GCS input bucket name

Fill in any other desired fields and click Try it!.

ℹ️

Sub-Organizations: If you are working within a Bitmovin sub-organization, add the X-Tenant-Org-Id header to the generated API request, set to the ID of the target organization.

Congratulations! Your GCS Service Account Input is now ready to use!
The ID contained in the result field of the response is your input ID, which you can use in future encoding jobs.

Use a Bitmovin SDK

Each of our Open API SDKs implements the Bitmovin API, making it easy to integrate with your project. Use them to create reusable input resources for your encodings:

from bitmovin_api_sdk import BitmovinApi, GcsServiceAccountInput

bitmovin_api = BitmovinApi(api_key='YOUR_BITMOVIN_API_KEY')
# bitmovin_api = BitmovinApi(api_key='YOUR_BITMOVIN_API_KEY', tenant_org_id='YOUR_TENANT_ORG_ID')

with open('YOUR_JSON_SERVICE_ACCOUNT_CREDENTIALS.json', 'r') as f:
    gcs_input = GcsServiceAccountInput(
        name='YOUR-BITMOVIN-GSC-INPUT-NAME',
        bucket_name='bitmovin-encoding-input-bucket',
        service_account_credentials=f.read()
    )

gcs_input = bitmovin_api.encoding.inputs.gcs_service_account.create(gcs_input)
print(f'Successfully created GCS Service Account with Input ID: {gcs_input.id}')

import com.bitmovin.api.sdk.BitmovinApi;
import com.bitmovin.api.sdk.model.GcsServiceAccountInput;
import java.nio.file.Files;
import java.nio.file.Paths;

BitmovinApi bitmovinApi = BitmovinApi.builder()
    .withApiKey("YOUR_BITMOVIN_API_KEY")
    // .withTenantOrgId("YOUR_TENANT_ORG_ID")
    .build();

String credentials = new String(Files.readAllBytes(Paths.get("YOUR_JSON_SERVICE_ACCOUNT_CREDENTIALS.json")));

GcsServiceAccountInput gcsInput = new GcsServiceAccountInput();
gcsInput.setName("YOUR-BITMOVIN-GCS-INPUT-NAME");
gcsInput.setBucketName("bitmovin-encoding-input-bucket");
gcsInput.setServiceAccountCredentials(credentials);

gcsInput = bitmovinApi.encoding.inputs.gcsServiceAccount.create(gcsInput);
System.out.println("Successfully created GCS Service Account with Input ID: " + gcsInput.getId());

For more examples, see the Bitmovin API SDK Examples repository on GitHub.

ℹ️

Sub-Organizations: If you are working within a Bitmovin sub-organization, add the tenantOrgId option on the API client, set to the ID of the target organization.

Congratulations! Your GCS Service Account Input is now ready to use!

The ID contained in gcs_input.id the response is your input ID, which you can use in future encoding jobs.

Common Issues

Authentication failure on encoding start

Ensure the serviceAccountCredentials JSON key file is correctly serialized as a compact single-line string with all newlines inside the private_key escaped as \n. This should be the default format when the file is automatically downloaded.

403 Forbidden / permission denied

The Service Account does not have the Storage Object Viewer role. Verify the IAM bindings in the GCP Console under IAM & Admin → IAM and confirm the role is assigned to the correct Service Account email.

Encoding fails to download source file

Verify that bucketName exactly matches your bucket name (case-sensitive), that the name does not contain underscores (_), and that the file path used in the encoding job exists in the bucket.

Further Reading

• Service accounts overview  |  Identity and Access Management (IAM)  |  Google Cloud Documentation
• About Cloud Storage buckets  |  Google Cloud Documentation
• Required Permissions for GCS Buckets for Encoding Input and Output
• Setting Up a GCS Output (Service Account)