Skip to main content

​
Overview

This guide walks you through setting up Google Drive API access from creating a project to getting a long-lived refresh token. It uses the Desktop app OAuth flow which works reliably for scripts.
Important: Keep the app in Testing mode (no verification needed, but limited to test users). Always add your own email as a test user early to avoid “Access blocked: app not verified” errors.

​
Step 1: Create a Google Cloud Project

1

Open Google Cloud Console

Go to https://console.cloud.google.com/
2

Create new project

  1. Click the project dropdown in the top bar
  2. Click New Project
  3. Name it (e.g., gdrive-ingest-script)
  4. Click Create and wait a few seconds
3

Select the project

Select your new project from the top dropdown menu

​
Step 2: Enable the Google Drive API

1

Open API Library

Left menu: APIs & Services → Library
2

Enable Drive API

  1. Search for Google Drive API
  2. Click on it
  3. Click Enable
This step is critical! Add your email as a test user here to avoid “App not verified” errors later.
1

Open OAuth consent screen

Left menu: APIs & Services → OAuth consent screen
2

Choose user type

Select External user type → Click Create
3

Fill in app information

App name: GDrive Ingest Script
User support email: [email protected]
Developer contact: [email protected]
Click Save and Continue
4

Add scopes

  1. Click Add or remove scopes
  2. Search for drive
  3. Check .../auth/drive (full access)
  4. Click Update
  5. Click Save and Continue
5

Add test users (CRITICAL)

  1. Click + Add users
  2. Enter your email address (the one you’ll use to sign in)
  3. Click Add
  4. Click Save and Continue
This prevents “Access blocked: app not verified” errors during authorization.
6

Complete setup

Click Save and Continue through remaining steps → Back to dashboardYour app is now in Testing mode (valid for test users only — refresh token still works forever).

​
Step 4: Create Desktop OAuth Credentials

1

Open Credentials page

Left menu: APIs & Services → Credentials
2

Create credentials

  1. Click + Create Credentials
  2. Select OAuth client ID
3

Configure OAuth client

Application type: Desktop app
Name: gdrive-ingest-desktop
Click Create
4

Save credentials

You’ll see:
  • Client ID: Long string ending in .apps.googleusercontent.com
  • Client Secret: Starts with GOCSPX-
Copy both and save them for your .env file:
.env
CLIENT_ID="123456789012-abcdefgh.apps.googleusercontent.com"
CLIENT_SECRET="GOCSPX-your-secret-here"

​
Step 5: Get the Refresh Token

1

Build authorization URL

Replace YOUR_CLIENT_ID with your actual Client ID:
https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/drive&access_type=offline&response_type=code

https://accounts.google.com/o/oauth2/v2/auth?client_id=123456789012-abcde.apps.googleusercontent.com&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/drive&access_type=offline&response_type=code
2

Authorize and get code

  1. Open the URL in your browser
  2. Sign in with the test user email you added in Step 3
  3. Consent screen appears → Click Allow
  4. Google shows a verification code on the page (long string like 4/0AX4...)
  5. Copy the code
If you see “Access blocked: app not verified”, go back to Step 3 and make sure your email is added as a test user. Wait 1-5 minutes and retry.
3

Exchange code for refresh token

Run this curl command (replace placeholders):
curl -X POST \
  -d "code=YOUR_CODE_HERE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
  -d "grant_type=authorization_code" \
  https://oauth2.googleapis.com/token
You’ll get JSON response:
{
  "access_token": "ya29...",
  "expires_in": 3599,
  "refresh_token": "1//04longlongstring...",
  "scope": "https://www.googleapis.com/auth/drive",
  "token_type": "Bearer"
}
4

Save refresh token

Copy the refresh_token value (starts with 1//04... or 1//0g...):
.env
REFRESH_TOKEN="1//04your-refresh-token-here"
The refresh token is long-lived (valid until revoked or client secret reset).

​
Method 2: OAuth Playground (Alternative)

1

Open OAuth Playground

Go to https://developers.google.com/oauthplayground/
2

Configure with your credentials

  1. Click settings (gear icon) in top right
  2. Check “Use your own OAuth credentials”
  3. Enter your CLIENT_ID and CLIENT_SECRET
3

Select scopes

  1. In Step 1, find “Drive API v3”
  2. Select https://www.googleapis.com/auth/drive
  3. Click “Authorize APIs”
4

Sign in and authorize

Sign in with your Google account and authorize the app
5

Exchange for tokens

  1. In Step 2, click “Exchange authorization code for tokens”
  2. Copy the refresh_token value
This method is easier but gives full drive scope access.

​
Step 6: Configure the Script

1

Create .env file

cd ~/workspace/source/cloud/gdrive-ingest
cp .env.example .env
2

Edit .env with your credentials

nano .env
Fill in:
.env
CLIENT_ID="your-client-id.apps.googleusercontent.com"
CLIENT_SECRET="GOCSPX-your-secret-here"
REFRESH_TOKEN="1//04your-refresh-token-here"
3

Save the file

Press Ctrl+O to save, then Ctrl+X to exit nano

​
Step 7: Test the Script

./gdrive_ingest.sh https://example.com/test.mp3
Expected behavior:
  • Refreshes token automatically if needed
  • Shows folder list
  • Lets you pick destination
  • Downloads, organizes, and uploads

​
Troubleshooting

Cause: Your email is not added as a test user.Solution:
  1. Go to OAuth consent screen in Google Cloud Console
  2. Click Test users → + Add users
  3. Add your email address
  4. Wait 1-5 minutes and retry authorization
Cause: Refresh token doesn’t match client_id/secret.Solution:
  • Regenerate tokens using Step 5
  • Make sure you’re using the same client_id/secret pair
Cause: Wrong redirect URI in authorization URL.Solution: Make sure you’re using urn:ietf:wg:oauth:2.0:oob in the auth URL.
Cause: You’re not a test user.Solution: Add yourself again in OAuth consent screen → Test users.
This is normal!
  • Access token lasts ~1 hour
  • Script auto-refreshes using the long-lived refresh token
  • Refresh token remains valid indefinitely (until revoked)
Possible causes:
  • Client secret was reset
  • Token was manually revoked
  • App was removed from authorized apps
Solution: Regenerate using Step 5.

​
Security Notes

Never commit to git:
  • CLIENT_ID
  • CLIENT_SECRET
  • REFRESH_TOKEN
Best practices:

Use .env file

Store credentials in .env (already in .gitignore)

Dedicated account

Consider using a dedicated Google account (not your personal one)

Rotate credentials

Reset client secret periodically if you’re security-conscious

Restrict permissions

chmod 600 .env

​
Token Lifecycle

Key points:
  • Access token: Short-lived (~1 hour), used for API calls
  • Refresh token: Long-lived (years), used to get new access tokens
  • Script automatically refreshes access tokens as needed
  • You only need to do the OAuth flow once

​
Next Steps

Setup Guide

Complete the script setup

Usage Examples

Start uploading files

Telegram Integration

Optional: Enable Telegram downloads

Troubleshooting

Fix common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us