Authentication Overview

How Luci authenticates with external services: OAuth flows, API keys, SSH keys, credential storage, and token refresh patterns.

OAuth Flows

Microsoft 365 (Graph API)

Script: /home/lucienne/workspace/scripts/graph_api.py
Flow: OAuth 2.0 Device Code Flow (headless-friendly -- no browser required on server)
App ID: 8581071e-c8ea-4f51-88fa-64681082c5a6 (Azure AD registered app)
Authority: https://login.microsoftonline.com/common/oauth2/v2.0
Scopes requested:
offline_access (for refresh tokens)
Mail.ReadWrite, Mail.Send
Calendars.ReadWrite, Contacts.ReadWrite
Files.ReadWrite.All (OneDrive/SharePoint)
MailboxSettings.ReadWrite, Notes.ReadWrite.All
Tasks.ReadWrite, Team.ReadBasic.All, User.Read
Token cache: ~/.graph-api-token.json (access token + refresh token + expiry timestamp)
Personal OneDrive: Separate token at ~/.graph-api-token-personal.json
Legacy migration: Can migrate from ~/.cli-m365-msal.json (old m365 CLI cache) automatically

Login sequence: 1. python graph_api.py login requests a device code from Azure AD 2. User visits https://microsoft.com/devicelogin and enters the code 3. Script polls the token endpoint until user authenticates 4. Access token + refresh token cached to ~/.graph-api-token.json

Google Workspace (GWS)

CLI tool: gws (Node.js, installed at ~/.npm-global/bin/gws)
Credentials: ~/.config/gws/credentials.json (OAuth tokens)
Client secret: ~/.config/gws/client_secret.json (OAuth client configuration)
Helper: /home/lucienne/workspace/scripts/gdrive_helper.py wraps gws for Drive file operations
Auth portal: Generates consent URL, user pastes redirect URL back for code exchange

Auth Portal (Web-based Token Management)

Script: /home/lucienne/workspace/scripts/auth_portal.py
Port: 8788 (Tailscale: http://100.118.207.3:8788)
Purpose: Elmar can re-authenticate from his phone/laptop without terminal access
Supports: M365 device code flow rendered in-browser, GWS consent URL + code exchange
Dashboard: Token health status for both services

API Keys

All API keys are stored as environment variables on the server and documented in ~/.claude/vault/secrets/api-keys.md. The master reference with full per-project breakdown lives in SecondBrain.

Services with API keys:

Service	Env Var	Auth Method
Google Gemini	`GEMINI_API_KEY`	API key (free tier)
Google Gemini (paid)	`GEMINI_API_KEY_PAID`	API key (Tier 2 Postpay)
Anthropic	`ANTHROPIC_API_KEY`	API key
OpenAI/Codex	`OPENAI_API_KEY`	CLI only (OAuth)
Brave Search	`BRAVE_API_KEY`	API key (MCP server)
Tavily	`TAVILY_API_KEY`	API key (MCP server)
WebScrapingAPI	`WEBSCRAPINGAPI_KEY`	API key
Hetzner Cloud	`HETZNER_API_TOKEN`	API token
Linear	Static token	API token
Asana	Static token	Personal access token
Notion	Static token	Integration token
Make.com	Webhook URL	No auth (URL is the secret)
Fireflies.ai	Static token	GraphQL API key
Home Assistant	Static token	Long-lived access token

Key patterns: - One Anthropic key shared across projects - Separate OpenAI/Gemini keys per project - 4 GitHub PATs -- Mission Control PAT (ghp_Kjhq...) is the active one for Luci - Luci uses MC PAT via ~/.git-credentials (credential store) for all HTTPS git push

SSH Keys

SSH keys are stored at ~/.claude/vault/secrets/ssh/: - id_ed25519 / id_ed25519.pub -- primary Ed25519 keypair - echo-key.pem -- PEM key for Echo server access - config -- SSH client configuration - README.md -- documentation

Infrastructure connectivity: - Luci (Hetzner): lucienne@100.118.207.3 (Tailscale IP) - SSH config and network topology documented in ~/.claude/vault/infrastructure/

Credential Storage Locations

Location	Contents
`~/.claude/vault/secrets/api-keys.md`	Quick reference of all API keys
`~/.claude/vault/secrets/api_keys.env`	Environment variable exports
`~/.claude/vault/secrets/passwords.md`	POPIA document passwords (SA financial institutions)
`~/.claude/vault/secrets/ssh/`	SSH keys and config
`~/.claude/vault/secrets/ha-credentials.env`	Home Assistant credentials
`~/.claude/vault/secrets/spotify-credentials.env`	Spotify API credentials
`~/.graph-api-token.json`	M365 work OAuth token cache
`~/.graph-api-token-personal.json`	M365 personal OAuth token cache
`~/.config/gws/credentials.json`	Google Workspace OAuth tokens
`~/.config/gws/client_secret.json`	Google OAuth client config
`~/.dropbox-api-token.json`	Dropbox API token
`~/.git-credentials`	GitHub PAT for git push
Environment variables	Runtime API keys (loaded from `.bashrc`)

Token Refresh Patterns

M365 Graph API

Access tokens expire after ~1 hour (3600s)
graph_api.py checks expires_on timestamp before every request
If expired, auto-refreshes using the stored refresh token
If refresh fails, prints error instructing user to run python graph_api.py login
Refresh token itself is long-lived but can be revoked

Google Workspace

Managed by the gws CLI tool internally
gdrive_helper.py has retry logic for transient errors (500, 503, 429) with exponential backoff

OAuth Health Check

Script: /home/lucienne/workspace/scripts/oauth_health_check.py
Monitors both GWS and M365 token health
Writes status JSON to ~/workspace/data/oauth-health-status.json
Alerts via Telegram on token expiry/failure
Can run in quiet mode for heartbeat embedding

Unified Cloud Search

Script: /home/lucienne/workspace/scripts/search_all.py
Searches M365 Work OneDrive, Personal OneDrive, Google Drive, and Dropbox in parallel
Each search function loads its own token file independently
Can trigger token refresh via the auth portal (http://localhost:8788)

Key Takeaways

M365 uses OAuth 2.0 Device Code Flow via graph_api.py -- headless-friendly, tokens cached at ~/.graph-api-token.json
Google Workspace uses gws CLI with OAuth tokens at ~/.config/gws/
Auth portal on port 8788 lets Elmar re-authenticate from any device via Tailscale
All API keys documented in ~/.claude/vault/secrets/api-keys.md, loaded as environment variables
Token health is monitored by oauth_health_check.py with Telegram alerts on failure
M365 tokens auto-refresh on every request; manual login only needed when refresh token expires
SSH keys stored in ~/.claude/vault/secrets/ssh/ with Ed25519 as primary

Wiki