> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tornadoapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Google Drive

> Configure Google Drive delivery for your downloads

## Overview

Deliver uploaded videos to a Google Drive folder using a **service account**. Credentials are verified with a live Drive API call before saving.

<Info>
  Google Drive uses **service account** authentication (the same kind of JSON key as GCS) and resumable uploads. The service account must have access to the target folder — share the Drive folder with the service account's email address.
</Info>

## Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Request Body

<ParamField body="service_account_json" type="string" required>
  Service account JSON credentials (the entire JSON file content as a string).
</ParamField>

<ParamField body="folder_id" type="string">
  Target Drive folder ID (the part after `/folders/` in the folder URL). Leave empty to upload to the service account's own Drive root. Default: `""` (root).
</ParamField>

<ParamField body="folder_prefix" type="string">
  Optional folder prefix for organizing uploads (e.g., `downloads/2024/`)
</ParamField>

<ParamField body="base_folder" type="string" default="videos">
  Base folder name for uploaded files. Defaults to `videos` if not specified.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Success confirmation message
</ResponseField>

<ResponseField name="provider" type="string">
  Storage provider type: `gdrive`
</ResponseField>

<ResponseField name="folder_id" type="string">
  The configured target folder ID (empty when using the service account root)
</ResponseField>

<ResponseField name="folder_prefix" type="string">
  The configured folder prefix (if provided)
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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-gcp-project\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"tornado@my-gcp-project.iam.gserviceaccount.com\"}"
    }'
  ```

  ```python Python (from file) theme={null}
  import requests
  import json

  # Load service account JSON file (recommended)
  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())
  ```

  ```json Response theme={null}
  {
    "message": "Google Drive configured successfully",
    "provider": "gdrive",
    "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "folder_prefix": null
  }
  ```
</CodeGroup>

## Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Google Drive configured successfully",
    "provider": "gdrive",
    "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "folder_prefix": null
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request - Invalid JSON theme={null}
  {
    "error": "Invalid configuration: invalid service account JSON"
  }
  ```

  ```json 400 Bad Request - Validation Failed theme={null}
  {
    "error": "Credential validation failed: insufficient permissions on folder"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API Key"
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
    "error": "Google Drive storage configuration is temporarily unavailable"
  }
  ```
</ResponseExample>

## Setup

<Steps>
  <Step title="Create a service account">
    In Google Cloud Console, go to **IAM & Admin** > **Service Accounts** > **Create Service Account**, then create a **JSON key** under **Keys** > **Add Key**.
  </Step>

  <Step title="Enable the Drive API">
    Enable the **Google Drive API** for the service account's project.
  </Step>

  <Step title="Share the target folder">
    In Google Drive, share the destination folder with the service account's email address (`...@PROJECT.iam.gserviceaccount.com`) and grant **Editor** access. Copy the folder ID from the URL (`drive.google.com/drive/folders/<FOLDER_ID>`).
  </Step>

  <Step title="Configure Tornado">
    Send the `folder_id` and the minified `service_account_json` to `POST /user/gdrive`.
  </Step>
</Steps>

<Warning>
  A service account has its own small Drive quota. To deliver into a Workspace/shared drive with adequate storage, share a folder from an account that owns the quota and pass its `folder_id`.
</Warning>

<Note>
  Google Drive is available as a **pre-configured** delivery target via this endpoint only. It is **not** supported as inline `storage` credentials in `POST /jobs` (inline storage supports S3, Azure Blob, GCS, and Alibaba OSS).
</Note>