Skip to content
msgvault
GitHub stars

Google OAuth Setup

msgvault requires OAuth credentials to access the Gmail API. This guide walks through the complete setup.

Step 1: Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Note your project ID

Step 2: Enable the Gmail API

  1. Navigate to APIs & Services > Library
  2. Search for “Gmail API”
  3. Click Enable
  1. Go to APIs & Services > OAuth consent screen
  2. Choose External user type (or Internal for Google Workspace)
  3. Fill in required fields:
    • App name: msgvault
    • User support email: your email
    • Developer contact email: your email
  4. Click Save and Continue
  5. On the Scopes page, click Add or Remove Scopes
  6. Add the scope: https://www.googleapis.com/auth/gmail.modify
  7. Save and continue through the remaining screens
  8. Under Test users, add all Gmail addresses you want to sync

Step 4: Create OAuth Client Credentials

  1. Go to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Choose Desktop application
  4. Name it msgvault Desktop Client
  5. Click Create
  6. Download the JSON file
  7. Save it as client_secret.json in a secure location

Step 5: Configure msgvault

Create ~/.msgvault/config.toml:

[oauth]
client_secrets = "/path/to/your/client_secret.json"


[sync]
rate_limit_qps = 5

Step 6: Add Your Account

Terminal window
msgvault add-account you@gmail.com

This opens your browser to Google’s OAuth consent page. Sign in, grant access, and tokens are stored locally in ~/.msgvault/tokens/.

Headless Server Setup

When running msgvault on a headless server (SSH, VPS, Docker), there is no browser available for the standard OAuth flow. Use the device authorization flow instead:

Terminal window
msgvault add-account you@gmail.com --headless

This displays instructions:

Starting device code flow...


1. Open this URL in any browser:
   https://www.google.com/device


2. Enter this code when prompted:
   ABC-XYZ


Waiting for authorization...
  1. Run the command above on the server
  2. Open https://www.google.com/device on any device with a browser (phone, laptop)
  3. Sign in to your Google account
  4. Enter the displayed code
  5. Grant access to msgvault
  6. The server automatically detects authorization and stores the token

Once authorized, all other commands work normally. Tokens are stored in ~/.msgvault/tokens/you@gmail.com.json and refreshed automatically.