Skip to main content
OAuth credentials allow AgenticPal to authenticate users and access their Google data securely.

​
Create OAuth Client ID

1

Navigate to Credentials

In the Google Cloud Console, go to APIs & Services > Credentials.
2

Create credentials

Click Create Credentials and select OAuth client ID.
3

Select application type

Choose Desktop app as the application type.
Desktop app credentials work for both CLI and local development. For web deployments, you’ll need to create a “Web application” OAuth client instead.
Give your OAuth client a name (e.g., “AgenticPal Desktop”) and click Create.
4

Download credentials

After creation, a dialog will appear with your client ID and secret. Click Download JSON to save the credentials file.
Keep this file secure! It contains your OAuth client secret. Never commit it to version control.

​
Configure Credentials File

The downloaded JSON file needs to be placed in your project directory.
1

Rename the file

Rename the downloaded file to credentials.json.
2

Place in project root

Move credentials.json to your AgenticPal project root directory:
mv ~/Downloads/client_secret_*.json /path/to/agenticpal/credentials.json
3

Verify file structure

Your credentials.json should have this structure:
{
  "installed": {
    "client_id": "your-client-id.apps.googleusercontent.com",
    "project_id": "your-project-id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "your-client-secret",
    "redirect_uris": ["http://localhost"]
  }
}
4

Add to .gitignore

Ensure credentials.json is in your .gitignore:
credentials.json
token.json
.env

​
Required Scopes

AgenticPal uses the following OAuth scopes defined in auth.py:10: 
DEFAULT_SCOPES = (
    "https://www.googleapis.com/auth/calendar",
    "https://mail.google.com/",
    "https://www.googleapis.com/auth/tasks",
)

​
Scope Details

Permissions granted:
  • View and edit calendar events
  • Create and delete events
  • Manage calendar settings
Used for:
  • Adding meetings and appointments
  • Listing upcoming events
  • Modifying or deleting calendar entries
Permissions granted:
  • Read all emails
  • Send emails
  • Modify labels and filters
  • Manage drafts
Used for:
  • Reading and summarizing emails
  • Email search and filtering
  • Future: Email management features
This is a restricted scope. Apps using this scope require Google verification for production use.
Permissions granted:
  • View and edit tasks
  • Create and delete tasks
  • Manage task lists
Used for:
  • Creating and managing to-do items
  • Marking tasks complete
  • Listing tasks and task lists

​
Authentication Flow

When you first run AgenticPal, the authentication flow works as follows:
  1. Check for existing token: AgenticPal looks for token.json (auth.py:34)
  2. Token refresh: If the token exists but is expired, it attempts to refresh (auth.py:37-41)
  3. Browser consent: If no valid token exists, a browser window opens for OAuth consent (auth.py:49-50)
  4. Token caching: After successful authentication, the token is saved to token.json (auth.py:52)
if not creds or not creds.valid:
    if not credentials_file.exists():
        raise FileNotFoundError(
            f"Missing OAuth client file at {credentials_file}. "
            "Download it from Google Cloud Console (OAuth client ID)."
        )
    flow = InstalledAppFlow.from_client_secrets_file(str(credentials_file), scope_list)
    creds = flow.run_local_server(port=0, prompt="consent")
    token_file.parent.mkdir(parents=True, exist_ok=True)
    token_file.write_text(creds.to_json())

​
Testing Authentication

You can test your OAuth setup by running the auth module directly: 
python -m auth
If successful, you’ll see: 
Authentication succeeded; token cached at token.json
If you see “unverified app” warnings during OAuth, this is normal during development. Click Advanced and then Go to [App Name] (unsafe) to proceed.

​
Troubleshooting

  • Ensure credentials.json is in your project root directory
  • Verify the file name is exactly credentials.json (lowercase)
  • Check that the file contains valid JSON
  • Verify you’ve added your email as a test user in the OAuth consent screen
  • Ensure all required APIs are enabled in Google Cloud Console
  • Check that your Google account matches the test user email
  • Delete token.json and re-authenticate
  • This happens if the token was revoked in Google Account settings
  • Run python -m auth to generate a new token

​
Next Steps

Environment Configuration

Set up environment variables and LLM API keys

Build docs developers (and LLMs) love

Get started for freeTalk to us