Skip to content

Google

service_jtl — Endpoints: Google

Base prefix: /api/v1/jtl (router-level prefix applied by the service).

These endpoints manage Google OAuth credentials used by the JTL service (Gmail/Sheets clients).

Routes

  • POST /auth
  • Description: Upload a Google client JSON (OAuth client secrets) and receive an auth_url to start the OAuth flow.
  • Content-Type: multipart/form-data
  • Form fields:
    • json_file (file, required) — Google client secrets JSON (client_secret.json).
    • display_name (string, optional) — human label for the credential.
    • scopes (repeatable, optional) — OAuth scopes; if omitted sensible defaults are used (openid, userinfo.email, gmail.readonly, spreadsheets).
  • Response: GoogleAuthStartResponse (status, auth_url, state).

Example curl (upload client secret and request auth URL):

curl -X POST "http://localhost:8003/api/v1/jtl/auth" \
  -F "display_name=JTL Sheets" \
  -F "json_file=@/path/to/client_secret.json" \
  -F "scopes=https://www.googleapis.com/auth/spreadsheets" \
  -F "scopes=https://www.googleapis.com/auth/gmail.readonly"
  • GET /oauth/callback?code=...&state=...
  • Description: OAuth redirect target that exchanges code + state for tokens and persists them to the DB.
  • Response: GoogleAuthCallbackResponse (credential id, client_id, scopes, authenticated_email, expires_at).

Example (called automatically by Google after user consents):

GET /api/v1/jtl/oauth/callback?code=...&state=...
  • POST /credentials/{credential_id}/refresh
  • Description: Force-refresh access token for a stored credential. Returns TokenRefreshResponse.

  • Notes: If refresh fails with invalid_grant, the endpoint returns needs_reauth=True and an operator should reauthorize.

  • DELETE /credentials/{credential_id} — Delete a stored credential. Returns CredentialDeleteResponse.

  • GET /credentials/ — List stored credentials (DB objects returned by CRUD layer).

  • POST /credentials/{credential_id}/toggle-active — Toggle which credential is active (only one should be active at a time). Returns CredentialToggleResponse.

  • POST /credentials/{credential_id}/reauthorize — Start an OAuth flow using stored client config to re-authorize an existing credential (returns auth_url).

Models

  • Request/response Pydantic models live in backend/service_jtl/app/models/google.py (e.g. GoogleAuthStartResponse, GoogleAuthCallbackResponse, TokenRefreshResponse).

Implementation

Operational notes

  • oauth_states is an in-memory map used to hold Flow state → serialized flow data while the user completes the OAuth consent. In production use Redis or a DB-backed store to survive restarts and scale horizontally.
  • The redirect base used to build the OAuth redirect URI is controlled by the JTL_GOOGLE_OAUTH_PREFIX env var.
  • After refresh, the service uses Google's tokeninfo endpoint to compute a robust expiry time and persists expires_at to the DB.