Skip to main content
Google OAuth credentials are not baked into the build. You must create your own OAuth credentials through Google Cloud Console. This is a one-time setup that takes about 10 minutes.

​
Overview

Craft Agents integrates with Google services (Gmail, Calendar, Drive, Docs, Sheets) using OAuth 2.0 with PKCE (Proof Key for Code Exchange). Your credentials are stored encrypted locally using AES-256-GCM encryption.

​
Prerequisites

​
Complete Setup Guide

1

Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Click Select a project → New Project
  3. Enter a project name (e.g., “My Craft Agent”)
  4. Click Create
  5. Note your Project ID for reference
2

Enable Required APIs

Go to APIs & Services → Library and enable the APIs you need:
For email integration
  • Read, send, and manage email
  • Create and manage drafts
  • Label and organize messages
  • Mark messages as read/unread
Search for “Gmail API” and click Enable
For calendar integration
  • View and manage calendar events
  • Create and update events
  • Manage calendar access
Search for “Google Calendar API” and click Enable
For file storage integration
  • Access and manage files
  • Upload and download documents
  • Share and organize folders
Search for “Google Drive API” and click Enable
You can enable multiple APIs for the same project. Enable only the APIs you plan to use.
3

Configure OAuth Consent Screen

  1. Go to APIs & Services → OAuth consent screen
  2. Select External user type (unless you have Google Workspace)
  3. Click Create
Fill in required fields:
  • App name: e.g., “My Craft Agent”
  • User support email: Your email address
  • Developer contact information: Your email address
  1. Click Save and Continue
  2. Scopes: Skip this step (click Save and Continue)
  3. Test users: Add yourself as a test user
    • Click Add Users
    • Enter your Google email
    • Click Add
  4. Click Save and Continue
  5. Review and click Back to Dashboard
External apps in testing mode can only be used by test users you add. For production use with multiple users, you’ll need to get your app verified by Google.
4

Create OAuth Credentials

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth Client ID
  3. Application type: Select Desktop app
  4. Name: e.g., “Craft Agent Desktop”
  5. Click Create
  6. A dialog appears with your credentials:
    • Client ID: something.apps.googleusercontent.com
    • Client Secret: your-client-secret
  7. Click Download JSON (optional, for backup)
  8. Copy both the Client ID and Client Secret
Keep your Client Secret secure. Never commit it to version control or share it publicly.
5

Configure in Craft Agent

Option 1: Let the agent guide youSimply tell the agent:
Connect to my Gmail account
The agent will prompt you for your Google OAuth credentials during setup.Option 2: Manual configurationWhen setting up a Google source, add these fields to your source’s config.json:
{
  "api": {
    "googleService": "gmail",
    "googleOAuthClientId": "your-client-id.apps.googleusercontent.com",
    "googleOAuthClientSecret": "your-client-secret"
  }
}

​
OAuth Flow

When you authenticate:
  1. Browser opens to Google consent screen
  2. Sign in with your Google account
  3. Review permissions and click Allow
  4. Redirected back to Craft Agent
  5. Tokens stored encrypted in ~/.craft-agent/credentials.enc

​
Scopes by Service

  • https://www.googleapis.com/auth/gmail.modify - Read, trash, labels, mark read/unread
  • https://www.googleapis.com/auth/gmail.compose - Create and send drafts
  • https://www.googleapis.com/auth/userinfo.email - Access email address
  • https://www.googleapis.com/auth/calendar - Full calendar access
  • https://www.googleapis.com/auth/userinfo.email - Access email address
  • https://www.googleapis.com/auth/drive - Full Drive access
  • https://www.googleapis.com/auth/userinfo.email - Access email address
  • https://www.googleapis.com/auth/documents - Full Docs access
  • https://www.googleapis.com/auth/userinfo.email - Access email address
  • https://www.googleapis.com/auth/spreadsheets - Full Sheets access
  • https://www.googleapis.com/auth/userinfo.email - Access email address

​
Token Refresh

Google access tokens expire after 1 hour. Craft Agent automatically refreshes them using the refresh token:
  • Access tokens are refreshed automatically before API calls
  • Refresh tokens are long-lived (no expiration)
  • Your credentials are stored securely for automatic refresh

​
Security Notes

Important Security Practices
  • Your OAuth credentials are stored encrypted in ~/.craft-agent/credentials.enc using AES-256-GCM
  • Client ID and Client Secret are stored alongside tokens for automatic refresh
  • Never commit credentials to version control
  • For production use, consider getting your OAuth consent screen verified by Google
  • Test user limit: 100 users while app is in testing mode

​
Troubleshooting

You haven’t provided OAuth credentials. Either:
  1. Provide clientId and clientSecret in source config
  2. Set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET environment variables (development only)
Your OAuth consent screen is not properly configured:
  1. Verify you added yourself as a test user
  2. Check that required APIs are enabled
  3. Ensure redirect URI matches (should be http://localhost:{port}/callback)
Possible CSRF attack detected. This can happen if:
  1. You have multiple OAuth flows running simultaneously
  2. Your system time is incorrect
  3. You’re behind a proxy that modifies requests
Try again with a fresh authentication flow.
Refresh token might be invalid:
  1. Re-authenticate to get a new refresh token
  2. Ensure offline_access and prompt=consent are used during OAuth (automatic in Craft Agent)
  3. Check that Client ID and Client Secret are stored correctly

​
Environment Variables (Development)

For development/testing, you can set OAuth credentials as environment variables:
.env
# OPTIONAL - for development/testing only
# Users should provide their own credentials via source configuration
GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
Environment variables serve as a fallback. User-provided credentials in source config take precedence.

Build docs developers (and LLMs) love

Get started for freeTalk to us