Skip to main content
Google Tasks, Calendar, and Gmail integration requires OAuth 2.0 credentials from Google Cloud Console. This tutorial walks through creating a project, enabling APIs, downloading credentials, and completing the first authentication flow.

​
Prerequisites

  • A Google account
  • ollim-bot installed and running
  • A web browser accessible from the machine running ollim-bot (the OAuth flow opens a browser window)
1

Create a Google Cloud project

Go to the Google Cloud Console and create a new project (or select an existing one).
  1. Click the project dropdown at the top of the page
  2. Click New Project
  3. Enter a name (e.g. ollim-bot) and click Create
2

Enable the required APIs

Navigate to APIs & Services > Library and enable these three APIs:
APIUsed for
Google Tasks APITask management — list, create, complete, delete
Google Calendar APIEvent management — list, create, show, delete
Gmail APIRead-only email access — list unread, read, search
Search for each API by name and click Enable.
3

Configure the OAuth consent screen

Navigate to APIs & Services > OAuth consent screen.
  1. Select External as the user type and click Create
  2. Fill in the required fields (app name, user support email, developer email)
  3. On the Scopes page, click Add or Remove Scopes and add:
    • https://www.googleapis.com/auth/tasks
    • https://www.googleapis.com/auth/calendar.events
    • https://www.googleapis.com/auth/gmail.readonly
  4. On the Test users page, add your Google account email
For personal use, the project can stay in “Testing” mode — no verification needed. Only accounts listed as test users can complete the OAuth flow.
4

Create OAuth client credentials

Navigate to APIs & Services > Credentials.
  1. Click Create Credentials > OAuth client ID
  2. Select Desktop application as the application type
  3. Give it a name (e.g. ollim-bot)
  4. Click Create
  5. Click Download JSON to download the credentials file
The downloaded file has this structure:
credentials.json
{
  "installed": {
    "client_id": "...",
    "project_id": "...",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_secret": "...",
    "redirect_uris": ["http://localhost"]
  }
}
The application type must be Desktop application — not “Web application”. ollim-bot uses InstalledAppFlow, which expects the "installed" key in the JSON.
5

Save credentials to the data directory

Move the downloaded file to ~/.ollim-bot/state/credentials.json:
mkdir -p ~/.ollim-bot/state
mv ~/Downloads/client_secret_*.json ~/.ollim-bot/state/credentials.json
ollim-bot looks for credentials at this exact path:
~/.ollim-bot/state/credentials.json
If the file is missing when a Google API call is made, the bot exits with:
Missing ~/.ollim-bot/state/credentials.json -- download OAuth client credentials
from Google Cloud Console and save at that path
6

Complete the first authentication flow

Start the bot (or trigger any Google integration feature):
ollim-bot
On the first Google API call, ollim-bot:
  1. Reads ~/.ollim-bot/state/credentials.json
  2. Starts a local HTTP server on 127.0.0.1 (random port)
  3. Opens your browser to Google’s OAuth consent page
  4. After you grant access, captures the authorization code
  5. Exchanges the code for access and refresh tokens
  6. Saves the tokens to ~/.ollim-bot/state/token.json
On subsequent runs, the saved token is reused automatically. Expired tokens are refreshed in the background without opening a browser.
Ask the bot to list your tasks or calendar events to trigger the OAuth flow and verify everything works.

​
Token lifecycle

ollim-bot manages tokens automatically through get_credentials() in google/auth.py:
ScenarioBehavior
token.json exists, token validUsed immediately — no network call
token.json exists, token expiredRefreshed via the refresh token, token.json updated
token.json missingFull OAuth flow — opens browser for consent
credentials.json missingExits with an error message
The token file at ~/.ollim-bot/state/token.json stores the access token, refresh token, and granted scopes. Do not edit it manually.

​
Adding or changing scopes

The OAuth scopes are defined in google/auth.py: 
SCOPES = [
    "https://www.googleapis.com/auth/tasks",
    "https://www.googleapis.com/auth/calendar.events",
    "https://www.googleapis.com/auth/gmail.readonly",
]
If you add a new Google service and need additional scopes:
  1. Add the scope string to the SCOPES list
  2. Delete ~/.ollim-bot/state/token.json
  3. Restart the bot — the OAuth consent flow runs again with the updated scopes
Existing tokens do not automatically gain new scopes. You must delete token.json and re-consent whenever scopes change.

​
Next steps

Google integration overview

How the Google services work together.

Optional integrations

Webhooks, timezone, and other optional features.

Google Tasks

Manage tasks through the bot and CLI.

Google Calendar

Manage calendar events through the bot and CLI.