Roboflow Docs

Google Cloud Storage Credentials

Create Google Cloud credentials securely for GCS Datasources.

Use this page when you want Roboflow to mirror a Google Cloud Storage bucket through Datasources.

For Google Cloud Storage, use Datasources and Bucket Mirror whenever you want ongoing sync, repeat imports, or metadata sidecar support. Do not build a signed URL or local download workflow for that use case.

Choose a Credential Type

Roboflow supports three Google Cloud access patterns for GCS Datasources:

  1. Impersonation: recommended: no keys, Roboflow uses short-lived tokens
  2. Direct Grant: grant Roboflow's service account read access directly on the bucket
  3. JSON Key: legacy: an exported service-account key, kept for backward compatibility

Impersonation and Direct Grant are keyless: no secret ever leaves your Google Cloud project. Google discourages exportable keys (and many organizations block them by policy), so prefer the keyless options.

Security Guidelines

Before you create any credential:

  1. Use a dedicated service account for Roboflow.
  2. Grant only Storage Object Viewer (roles/storage.objectViewer), scoped to the specific bucket.
  3. Prefer Impersonation or Direct Grant over an exported JSON key.
  4. Store credentials only in Roboflow Workspace Credentials or your own secret manager.
  5. You can revoke Roboflow's access at any time by removing the IAM grant.

Both keyless modes bind the grant to your workspace using a workspace token shown in the Create Credential modal (Google Cloud has no AWS-style External ID). Keep the token with the credential you are creating.

Use Service Account Impersonation

Recommended. No keys are exchanged. Roboflow uses service account impersonation to read your bucket with short-lived tokens.

  1. In Roboflow, open Add a Google Cloud (Impersonation) credential. The modal shows the required service account name (rf-datasource-<token>) and the Roboflow service account. Keep it open, you will need both values.

  2. Create the service account in your project with that exact name (the name embeds your workspace token, which binds the grant to your workspace):

    • Open the Service Accounts console.
    • Set the Service account ID (the part before @) to exactly rf-datasource-<token> from the modal, then click Create and continue → Done.

    Prefer the CLI?

    gcloud iam service-accounts create rf-datasource-<token> --project YOUR_PROJECT

  3. Grant that new service account read access to your bucket:

    • Open the Cloud Storage browser → your bucket → Permissions → Grant access.
    • New principals = the rf-datasource-<token>@… service account, Role = Storage Object Viewer → Save.

    Prefer the CLI?

    gsutil iam ch "serviceAccount:rf-datasource-<token>@YOUR_PROJECT.iam.gserviceaccount.com:roles/storage.objectViewer" gs://YOUR_BUCKET

  4. Grant the Roboflow service account the Service Account Token Creator role on the service account you just created. This is what lets Roboflow impersonate it:

    • In Service Accounts, click your rf-datasource-<token> service account → Permissions tab → Grant access.
    • New principals = the Roboflow service account shown in the modal, Role = Service Account Token Creator → Save.

    Prefer the CLI?

    gcloud iam service-accounts add-iam-policy-binding rf-datasource-<token>@YOUR_PROJECT.iam.gserviceaccount.com \
  --member="serviceAccount:ROBOFLOW_SERVICE_ACCOUNT" \
  --role="roles/iam.serviceAccountTokenCreator" --project YOUR_PROJECT

  5. Back in the modal, enter the service account email and save. Continue with Create the Credential in Roboflow.

The workspace token is tied to your workspace and credential type, so reopening the modal shows the same required service account name.

Use a Direct Bucket Grant

No keys are exchanged. Grant Roboflow's service account read access directly on the bucket, then prove the bucket belongs to your workspace with a marker object.

  1. In Roboflow, open Add a Google Cloud (Direct Grant) credential. The modal shows the Roboflow service account and your workspace token.

  2. Grant the Roboflow service account read access to your bucket:

    • Open the Cloud Storage browser → your bucket → Permissions → Grant access.
    • New principals = the Roboflow service account from the modal, Role = Storage Object Viewer → Save.

    Prefer the CLI?

    gsutil iam ch "serviceAccount:ROBOFLOW_SERVICE_ACCOUNT:roles/storage.objectViewer" gs://YOUR_BUCKET

  3. Upload a marker object at .roboflow/workspace-token whose contents include the workspace token (this binds the bucket to your workspace):

    • In the Cloud Storage browser, open your bucket, Create folder .roboflow, then Upload a small file named workspace-token whose contents are the token.

    Prefer the CLI?

    printf 'YOUR_WORKSPACE_TOKEN' | gsutil cp - gs://YOUR_BUCKET/.roboflow/workspace-token

  4. Save the credential in Roboflow, then continue with Create the Credential in Roboflow.

Roboflow reads the .roboflow/workspace-token marker during Datasource validation and fails without it.

Use a Service Account JSON Key

Legacy. Use only if the keyless options are not possible. Google discourages exportable keys, and many organizations block their creation by policy. Prefer the keyless Impersonation or Direct Grant options.

  1. Create a dedicated service account and grant it Storage Object Viewer on your bucket (same as steps 2-3 of Impersonation, but the name can be anything).

  2. Create a JSON key for it:

    • In Service Accounts, click your service account → Keys tab → Add key → Create new key → JSON → Create. Your browser downloads the key file.
    • If Create new key is disabled, an organization policy is blocking key export. Use Impersonation or Direct Grant instead.

    Prefer the CLI?

    gcloud iam service-accounts keys create key.json --iam-account SA_EMAIL

  3. In Roboflow, open Add a Google Cloud Storage (JSON Key) credential, enter your project ID, paste the JSON key, and save.

Create the Credential in Roboflow

After you set up the Google Cloud-side access:

  1. Go to Credentials in Workspace settings.
  2. Click Add Credential (or use a type-specific link: Impersonation, Direct Grant, JSON Key).
  3. Choose the Google Cloud Storage credential type you set up.
  4. Enter the service account email (Impersonation), the workspace token marker (Direct Grant), or the project ID + JSON key (JSON Key).
  5. Save the credential.
  6. Select that credential when you create the Datasource.

Next Step

After the credential is saved, continue with Datasources to configure bucket mirroring.