Skip to content

google endpoints — Credential management

Endpoints to manage Google OAuth credentials used by the invoice service (Gmail & Sheets). These routes handle uploading client JSON, starting OAuth flows, receiving callbacks, refreshing tokens and toggling the active credential.

Environment

  • INVOICE_GOOGLE_OAUTH_PREFIX: optional env var (default /api/v1/invoice) used as redirect-base when building OAuth redirect URLs. Set this if the service is mounted behind a proxy or uses a non-standard path.

Routes

  • POST /auth — Start OAuth flow
  • Form fields: json_file (file, required): the Google client JSON file uploaded by the user; display_name (string, optional); scopes (repeated string, optional).
  • Returns: GoogleAuthStartResponse with auth_url and state. User should visit auth_url and complete authorization in browser.

  • Notes: Builds redirect base using the request host + INVOICE_GOOGLE_OAUTH_PREFIX.

  • GET /oauth/callback — OAuth callback

  • Query params: code (string), state (string).

  • Returns: GoogleAuthCallbackResponse (stored credential metadata) or 400 on error.

  • POST /credentials/{credential_id}/refresh — Refresh token for a credential

  • Path param: credential_id (string).
  • Returns: TokenRefreshResponse with message, new_expiry or needs_reauth when refresh fails (e.g., invalid_grant).

  • Behavior: uses stored refresh token to refresh credentials and updates DB via CRUD.

  • DELETE /credentials/{credential_id} — Delete credential

  • Returns: CredentialDeleteResponse.

  • GET /credentials/ — List credentials

  • Returns: list of GoogleCredentials DB records.

  • POST /credentials/{credential_id}/toggle-active — Toggle active credential

  • Behavior: toggles active flag; the implementation ensures only one credential is active at a time.

  • Returns: CredentialToggleResponse (contains active boolean).

  • POST /credentials/{credential_id}/reauthorize — Re-authorize without re-upload

  • Path param: credential_id (string). Uses stored client fields to re-build a client JSON and create an OAuth flow (returns GoogleAuthStartResponse).

Security & operational notes

  • These routes are administrative: ensure they are protected by your service's auth (JWT) and only accessible to authorized operators.
  • Token refresh may fail with invalid_grant if client creds or refresh token are revoked — endpoints surface needs_reauth so callers can trigger re-authorization.
  • Keep uploaded client JSON files and stored client secrets secure; rotate or remove credentials when no longer needed.

Examples

  • Start OAuth (multipart upload):
curl -X POST "http://localhost:8000/api/v1/invoice/auth" \
  -F "display_name=invoice-bot" \
  -F "json_file=@/path/to/client_secret.json"
  • Refresh token:
curl -X POST "http://localhost:8000/api/v1/invoice/credentials/your-credential-id/refresh"