Google Drive Delivery

Read this first

Google Drive delivery works, but two current limitations decide how you must configure it.

1. The dashboard cannot save Drive as an organisation default today.The dashboard writes org-level storage through POST /settings/org-storage, which is gated by the ORG_STORAGE_PROVIDERS setting. That setting currently defaults to blob (Azure Blob only), so a Drive request is rejected before any credential is read:

{
  "detail": "Org-level default is not yet available for provider 'gdrive' (Rust rollout in progress). Available: ['blob']"
}

This is deliberate, not a misconfiguration. The Tornado API’s POST /user/gdrive handler does not accept the apply_to_all_keys flag that the org path depends on, so adding gdrive to ORG_STORAGE_PROVIDERS would not produce an org default. It would silently write a per-key config on whichever key the dashboard picked to authenticate its internal call, then fail the response check with The Tornado API did not confirm org-level scope.Until that ships, configure Drive with the direct API, POST /user/gdrive, on each API key you send jobs with. See Configure Tornado.

2. Finish onboarding before configuring Drive through the direct API.The onboarding wizard runs its steps in this order: destination → credentials → payment → key → request → delivered. The storage step therefore runs two steps before the API key is created.The Drive tile posts to POST /settings/org-storage, and that route resolves an existing active key from your organisation to authenticate its internal call. A brand new organisation has none. If the provider gate is enabled without changing this prerequisite, the route can return:

{
  "detail": "No usable API key in this organization — create one first (the org default is set through the Tornado API)."
}

Finish onboarding (pick Tornado bucket at the destination step, or any provider you already have credentials for), then configure Drive against your real API key.

What Drive delivery is, and is not

Tornado authenticates to Drive as a Google service account using a signed JWT, the same credential type as Google Cloud Storage. There is no OAuth consent screen and no “sign in with Google” redirect. You create the service account, you share a folder with it, you paste its JSON key. The backend requests exactly one scope:

https://www.googleapis.com/auth/drive.file

Google lists drive.file under non-sensitive scopes and marks it Recommended. It grants the ability to “Create new Drive files, or modify existing files, that you open with an app or that the user shares with an app while using the Google Picker API or the app’s file picker”. Tornado requests this narrower scope instead of unrestricted Drive access; effective access also depends on the service account, app authorization and sharing settings.

Use a dedicated destination folder or Shared Drive. The OAuth scope is not a replacement for reviewing the service account’s actual sharing permissions. Tornado lists accessible files when resolving names and deletes accessible delivered files; this guide does not promise that all pre-existing files are invisible under every Google authorization configuration.

Other behaviours worth knowing before you commit:

Behaviour	Drive	Other providers
Download URL	`https://drive.google.com/file/d/{id}/view` link with no Tornado URL expiry; object existence and Drive permissions still apply	Presigned URL, 24 hour validity
`folder_prefix` / `base_folder`	Flattened into the file name, no nested folders are created	Real object key path
Inline `storage` in `POST /jobs`	Not supported	S3, Blob, GCS, OSS supported
Upload throughput	Single sequential resumable stream	S3 multipart, parallel

base_folder and folder_prefix do not build a folder tree in Drive. A job with base_folder: "premier" and folder_prefix: "alex/test/" produces one file in your destination folder literally named premier/alex/test/my-video.mp4. The generic Folder Prefix diagrams in the Custom Storage page describe the object-storage providers, not Drive.

A service account is a Google identity with its own email address. It is not you, it cannot see your Drive, and it is not a member of your organisation unless you add it. Sharing the destination folder with that email address is not optional. Skip it and you land in one of two failure modes:

You set a folder_id the service account cannot see. Drive does not distinguish “not shared with you” from “does not exist”, so every upload fails with a 404 on a folder that is plainly sitting in your browser.
You left folder_id empty, so Tornado targets the service account’s own root Drive. That Drive belongs to a robot identity with no web UI you can log into, and it has no storage quota, so uploads fail with storageQuotaExceeded against a destination you cannot inspect.

Finding the service account’s email address

It is the client_email field inside the JSON key file you downloaded. It always ends in .iam.gserviceaccount.com:

jq -r .client_email service-account.json
# tornado-drive@my-project.iam.gserviceaccount.com

In the dashboard, paste the JSON into the Service account key (JSON) box first. The UI parses client_email out of it and shows a Share your folder with: row with a copy button, so you never have to open the file by hand.

Share the folder with that address as Editor, not Viewer or Commenter. Editor is the level that lets a collaborator “add files to the folder”.

Minimum and recommended access

Drive has no policy document. What you grant is one OAuth scope plus one sharing level, and Tornado picks the scope for you, so the only decision you make is the sharing level.

Minimum

What	Value
OAuth scope	`https://www.googleapis.com/auth/drive.file`, and only that. Tornado requests it and nothing else. You do not configure it; it is here so you can check the consent record and see that `drive`, `drive.readonly` and `drive.metadata` are absent
Cloud IAM roles on the service account	None. Cloud IAM does not grant Drive access. Assign nothing at project level
Drive API enablement	Google Drive API enabled on the project that owns the service account
Sharing, on a Shared Drive	The service account’s `client_email` added as a member with the Content manager role, on the drive or on a folder inside it
Sharing, on a My Drive folder	Editor on the folder. This is the minimum that permits upload, but see Storage quota: it fails anyway, for a different reason

Those cover everything Tornado calls: files.create (the resumable upload and its chunks), files.list (finding a delivered file by name, and the one-item validation call), and files.delete.

Contributor is not enough on a Shared Drive. Google’s own guidance is explicit that if you want members who cannot remove content, “give them Contributor, Commenter, or Viewer access only. These members can’t delete files.” Tornado deletes, so Contributor breaks the cleanup path. Content manager is the lowest role that both uploads and deletes.

Added	Why
A Shared Drive created for Tornado deliveries, rather than membership on an existing one	A dedicated drive separates delivered objects and access administration from unrelated data. Storage and upload quotas still depend on your Google Workspace configuration and current Google limits

Storage quota: use a Shared Drive, not My Drive

This is the single most important decision on this page, and the answer differs between My Drive and Shared Drives. Google’s Drive API documentation states it plainly:

Service accounts don’t have storage quota and can’t own any files. Instead, they must upload files and folders into shared drives, or use OAuth 2.0 to upload items on behalf of a human user.

Combine that with the ordinary Drive storage rule, “Only the files you own count toward your Google storage”, and the consequence follows:

My Drive folder shared with the service account: expect failure

When the service account uploads into a folder in someone’s My Drive, the service account becomes the owner of the new file. Storage is billed to the owner, and a service account has no quota to bill. Google rejects the upload with a 403:

{ "error": { "code": 403, "errors": [{ "reason": "storageQuotaExceeded" }] } }

The folder owner’s free space is irrelevant here. Their quota is not consumed because they do not own the file. Sharing the folder as Editor is necessary but not sufficient.

Shared Drive: the supported configuration

In a Shared Drive, the drive owns the files rather than any individual, so no personal quota is involved. Consumption counts against your Google Workspace organisation’s pooled storage. Tornado sends supportsAllDrives=true on every Drive upload, list and delete call, so Shared Drive targets work without any extra configuration on your side.Shared Drives require a work or school account. They are not available on personal @gmail.com accounts, and your Workspace edition and administrator must permit them.

Tornado’s JWT contains no sub claim, which means it does not use domain-wide delegation to impersonate a human user. The second option in Google’s guidance, “use OAuth 2.0 to upload items on behalf of a human user”, is therefore not available. A Shared Drive is the only configuration with a supported quota story.

Google Workspace caps uploads at 750 GB per day per user across My Drive and all shared drives. High-volume delivery can hit this. Nothing on the Tornado side raises it.

Setup

1. Create a Google Cloud project and enable the Drive API

Create the project

Go to console.cloud.google.com/projectcreate, or in the Cloud console open Menu > IAM & Admin > Create a Project.Enter a project name, optionally edit the project ID (it cannot be changed later), pick a location, then click Create.An existing project is fine. The project only carries the service account and the API enablement, it has nothing to do with where the files land.

Enable the Drive API

In the Cloud console go to Menu > APIs & Services > Library > Google Workspace, click Google Drive API, then click Enable.Direct link: console.cloud.google.com/apis/library/drive.googleapis.comOr with the CLI:

gcloud services enable drive.googleapis.com --project=YOUR_PROJECT_ID

Skipping this step produces a 403 with accessNotConfigured on the first upload, not at configuration time.

2. Create a service account and download its JSON key

Create the service account

Go to console.cloud.google.com/iam-admin/serviceaccounts, select your project, click Create service account, enter a name such as tornado-drive, then click Done.Assign no IAM roles. Cloud IAM roles do not grant Drive access. Drive permissions come exclusively from Drive sharing, which is step 3.

Create a JSON key

Click the service account’s email address, open the Keys tab, then Add key > Create new key, select JSON, and click Create. The file downloads automatically.Google notes that “This file is the only copy of this key. After you download the key file, you cannot download it again.”

Note the client_email

jq -r .client_email service-account.json

You need this address in the next step.

The JSON key is a long-lived private credential with no expiry. Store it in a secret manager, not in your repository. Tornado stores it in Azure Key Vault and never returns it, but the copy on your disk is your responsibility. Rotate it from the same Keys tab.

Shared Drive (recommended)
My Drive folder

Open drive.google.com and click Shared drives in the left sidebar.
Click New, name the drive, then click Create. Skip to step 3 if you are reusing an existing one.
Open the shared drive and click Manage members.
Paste the service account’s client_email address.
Set the role to Content manager or higher. Content manager can upload, edit, move and delete files, which matches what Tornado does on delivery and cleanup. Contributor is not enough, because it cannot delete.
Click Send.

You can target the shared drive’s root, or a folder inside it. Either works.

Read Storage quota first. This path is expected to fail at upload time with storageQuotaExceeded.

Open drive.google.com and select the folder.
Click Share.
Enter the service account’s client_email address.
Set the access level to Editor.
Click Send or Share.

Editor permissions cascade to everything inside the folder.

4. Find the folder ID

Open the folder in Drive and read it out of the address bar. The ID is everything after /folders/:

https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                       this is the folder_id

For the root of a Shared Drive, the ID in the URL after /drive/folders/ is the shared drive’s own ID, which is a valid parents value.

folder_id is optional in the API and defaults to "", which means “the service account’s own root Drive”. Treat it as required. The dashboard does: its Connect & verify button stays disabled until you fill it in, precisely because an empty value delivers into an invisible Drive.

5. Configure Tornado

Storage is resolved per API key. A configuration set on one key does not apply to your other keys. Run this for every key you send jobs with.

curl -X POST "https://api.tornadoapi.io/user/gdrive" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "service_account_json": "{\"type\":\"service_account\",\"project_id\":\"my-project\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"tornado-drive@my-project.iam.gserviceaccount.com\"}"
  }'

import json
import requests

with open("service-account.json") as f:
    sa_json = json.dumps(json.load(f))

response = requests.post(
    "https://api.tornadoapi.io/user/gdrive",
    headers={"x-api-key": "sk_your_api_key"},
    json={
        "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
        "service_account_json": sa_json,
    },
)
print(response.json())

{
  "message": "Google Drive configured successfully",
  "provider": "gdrive",
  "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "folder_prefix": null
}

Field reference

Field	Required	Notes
`service_account_json`	Yes	The whole JSON key file as a single string. Must contain `type: "service_account"`, `project_id`, `private_key` and `client_email`.
`folder_id`	No, but treat it as required	Destination folder ID. Defaults to `""`, meaning the service account’s root Drive.
`folder_prefix`	No	Flattened into the file name, see the warning above. Rejected if it starts with `/`, contains `//`, exceeds 512 characters, or contains any of the characters listed below the table.
`base_folder`	No	Defaults to `videos`. Also flattened into the file name.

Characters rejected in folder_prefix:

<  >  "  |  ?  *  \

The Drive field names differ from the GCS field names. Drive takes folder_id. GCS takes project_id and bucket. Drive accepts neither project_id nor bucket, and passing them changes nothing, because unknown fields are dropped silently rather than rejected. If you copied a working GCS payload and only swapped the URL, you have almost certainly configured the service account root Drive with an empty folder_id.

Through the dashboard

The dashboard’s Drive tile is blocked by limitation 1 above, so this is recorded for completeness rather than as a working path. The wire format nests the config under the provider key:

{
  "provider": "gdrive",
  "gdrive": {
    "service_account_json": "{\"type\":\"service_account\", ... }",
    "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz"
  }
}

The dashboard labels map to the API fields as Service account key (JSON) to service_account_json and Destination folder ID to folder_id. service_account_json is capped at 10,000 characters on this route. A standard Google key file is roughly 2.3 KB, so this only bites if you paste something other than the key.

What “verified” actually proves

POST /user/gdrive validates the credentials live before saving, and the dashboard button says Connect & verify. Be precise about what that check covers. The validation mints an OAuth token from the JSON key, then issues a one-item files.list. That proves the service account exists, the private key parses and signs, the Drive API is enabled on the project, and the drive.file scope is granted. It does not touch folder_id. The list call carries no folder filter, and under drive.file a fresh service account has created nothing, so it returns an empty list and the check passes. Nothing is written. The dashboard’s S3 probe was extended to write, read back, open and abort a multipart upload, and delete; Drive validation is a single read-only files.list and was not changed. If you have read the AWS S3 page, do not carry over what it says about the probe.

A green “verified” result does not prove that the folder ID is correct, that the folder exists, that it is shared with the service account, or that the target has usable storage quota. All four fail for the first time on your first real delivery. Always follow configuration with a test job.

curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "max_resolution": "360"
  }'

Then open the folder in Drive and confirm the file is there.

Troubleshooting

The job says `Completed` but nothing appears in my folder

Work through these in order.

Check which API key sent the job

The direct Drive configuration is per key. A key without it can inherit an organization destination of another provider, or use legacy/managed storage when no modern destination applies. Check the actual key and destination; configure Drive with the x-api-key you send these jobs with.

Check that folder_id was not empty

An empty or omitted folder_id sends everything to the service account’s own root Drive, which no human can browse. There is no read-back endpoint for Drive configuration, so if you are unsure, simply re-run POST /user/gdrive with the correct folder_id. It overwrites the previous config for that key.

Check the file name, not the folder tree

Drive does not create nested folders. If you set base_folder or folder_prefix, look for a flat file literally named videos/my-video.mp4 inside the destination folder, not for a videos subfolder.

Check that you are looking at the right Drive

A shared drive and a My Drive folder can have the same name. Confirm the ID in the URL matches the folder_id you configured.

Permission and lookup errors

Symptom	Cause	Fix
`Drive resumable init failed: 404 ... File not found: {folder_id}`	The service account cannot see the folder, or the ID is wrong. A folder that is not shared is indistinguishable from one that does not exist.	Share the folder with the `client_email` as Editor, or Content manager on a Shared Drive. Re-check the ID after `/folders/`.
`403 insufficientFilePermissions`	Shared as Viewer or Commenter, or as Contributor on a Shared Drive.	Raise to Editor, or Content manager on a Shared Drive. Contributor cannot delete, so cleanup fails.
`403 accessNotConfigured`	Drive API not enabled on the project that owns the service account.	Enable Google Drive API on that specific project.
`Credential validation failed: Failed to get Drive access token: 400 ... invalid_grant`	The key has been deleted or disabled in Cloud IAM, or the service account itself was removed.	Confirm the key is still listed under the service account’s Keys tab, and create a new one if not.
`Invalid configuration: Service account JSON missing 'client_email' field`	Wrong file. An OAuth client secret is not a service account key.	Re-download from Keys > Add key > Create new key > JSON.
`Invalid configuration: Service account JSON 'type' must be 'service_account'`	Same as above.	Same as above.
`Google Drive storage configuration is temporarily unavailable` (503)	Tornado’s credential vault is unreachable. Nothing to fix on your side.	Retry, then contact support.

Quota errors

Symptom	Cause	Fix
`403 storageQuotaExceeded` on every upload, to an empty folder, from an account with free space	The destination is a My Drive folder. The service account owns the uploaded file, and service accounts have no storage quota.	Move the destination to a Shared Drive and add the service account as Content manager. Nothing about the folder owner’s plan changes this.
`403 storageQuotaExceeded` on a Shared Drive	Your Workspace organisation’s pooled storage is full.	Free up pooled storage, or increase the organisation’s plan.
Uploads stop after roughly 750 GB in a day	Google’s per-user daily upload cap.	Wait 24 hours, or spread delivery across more than one destination.

Download link problems

The s3_url returned for a Drive delivery is a https://drive.google.com/file/d/{id}/view link with no Tornado URL-expiry parameter, and anyone opening it needs Drive permission on that file. Sharing the link with someone outside the folder’s access list will show them a request-access page. Tornado resolves that link by looking the file up by name inside the folder. Two jobs that produce identical file names will collide, and the lookup returns whichever one Drive answers with first. The generic backend delete also has a name-lookup path; job-file deletion for multi-clip results uses recorded, validated file IDs and a deletion journal. The ordinary single-file DELETE /jobs/{id}/file path currently uses S3 storage; do not rely on it to delete a Drive object. Remove such an object in Drive. Avoid duplicate names rather than relying on lookup order. Set a distinct per-job folder value on POST /jobs, which is folded into the file name and keeps the names unique.

Removing the configuration

curl -X DELETE "https://api.tornadoapi.io/user/gdrive" \
  -H "x-api-key: sk_your_api_key"

New downloads on that key use its remaining configuration, then any organization default, with legacy/managed storage as fallback when applicable. Files already delivered to Drive are left in place. Revoking the service account’s access in Drive, or deleting the JSON key in Cloud IAM, does not remove the stored configuration. Jobs will keep trying and failing until you run the DELETE.

Custom Storage

S3, Azure Blob, GCS and Alibaba OSS configuration

POST /user/gdrive

Full endpoint reference

API Reference

Jobs

Bulk

Metadata

Batch Operations

User

Google Drive Delivery

Read this first

What Drive delivery is, and is not

Finding the service account’s email address

Minimum and recommended access

Minimum

Recommended

Storage quota: use a Shared Drive, not My Drive

Setup

1. Create a Google Cloud project and enable the Drive API

2. Create a service account and download its JSON key

4. Find the folder ID

5. Configure Tornado

Field reference

Through the dashboard

What “verified” actually proves

Troubleshooting

The job says `Completed` but nothing appears in my folder

Permission and lookup errors

Quota errors

Download link problems

Removing the configuration

Custom Storage

POST /user/gdrive

​Read this first

​What Drive delivery is, and is not

​The step everyone misses: share the folder with the service account

​Finding the service account’s email address

​Minimum and recommended access

​Minimum

​Recommended

​Storage quota: use a Shared Drive, not My Drive

​Setup

​1. Create a Google Cloud project and enable the Drive API

​2. Create a service account and download its JSON key

​3. Share the destination folder with the service account

​4. Find the folder ID

​5. Configure Tornado

​Field reference

​Through the dashboard

​What “verified” actually proves

​Troubleshooting

​The job says Completed but nothing appears in my folder

​Permission and lookup errors

​Quota errors

​Download link problems

​Removing the configuration

​Related

Custom Storage

POST /user/gdrive

Read this first

What Drive delivery is, and is not

The step everyone misses: share the folder with the service account

Finding the service account’s email address

Minimum and recommended access

Minimum

Recommended

Storage quota: use a Shared Drive, not My Drive

Setup

1. Create a Google Cloud project and enable the Drive API

2. Create a service account and download its JSON key

3. Share the destination folder with the service account

4. Find the folder ID

5. Configure Tornado

Field reference

Through the dashboard

What “verified” actually proves

Troubleshooting

The job says `Completed` but nothing appears in my folder

Permission and lookup errors

Quota errors

Download link problems

Removing the configuration

Related