OAuth2 Authentication Guide
Learn how to use OAuth2 authentication with Kagura AI to access Google models (like Gemini) without managing API keys.
📌 Important Note
For most users, using API Keys is recommended as it's simpler and faster to set up: - Gemini: Get API key from Google AI Studio → Set
GOOGLE_API_KEY- Claude: Get API key from Anthropic Console → SetANTHROPIC_API_KEY- OpenAI: Get API key from OpenAI Platform → SetOPENAI_API_KEYOAuth2 is an advanced feature for specific use cases like: - Multi-user applications where each user authenticates with their own Google account - Production environments requiring strict access controls - Applications that need per-user quota management
Currently, only Google/Gemini supports OAuth2. Claude and OpenAI use API keys only.
Overview
Kagura AI supports OAuth2 authentication for Google services only, allowing you to:
- No API Key Management: Use Google models without storing API keys
- Secure Authentication: OAuth2 tokens are encrypted locally (Fernet/AES-128)
- Automatic Token Refresh: Tokens are automatically refreshed when expired
- Simple CLI Commands: Easy login/logout/status management
Prerequisites
- Google Cloud Project with Generative Language API enabled
- OAuth 2.0 Client ID (Desktop application type)
- Kagura AI with OAuth support installed:
Setup Guide
Step 1: Create OAuth 2.0 Client ID
- Go to Google Cloud Console - Credentials
- Click "Create Credentials" → "OAuth client ID"
- Select "Desktop app" as the application type
- Name it (e.g., "Kagura AI Desktop")
- Click "Create"
- Download the JSON file
Step 2: Save Client Secrets
Save the downloaded JSON file as ~/.config/kagura/client_secrets.json:
mkdir -p ~/.kagura
mv ~/Downloads/client_secret_*.json ~/.config/kagura/client_secrets.json
chmod 600 ~/.config/kagura/client_secrets.json
Important: Keep this file secure! It contains your OAuth client credentials.
Step 3: Login
Run the kagura auth login command:
This will:
1. Open your browser for Google OAuth2 authentication
2. Ask you to authorize Kagura AI to access Google Generative Language API
3. Save encrypted credentials to ~/.config/kagura/credentials.json.enc
Output:
Step 4: Verify Authentication
Check your authentication status:
Output:
Using OAuth2 in Your Code
Basic Usage with LLMConfig
from kagura.core.llm import LLMConfig, call_llm
# Configure OAuth2 authentication
config = LLMConfig(
model="gemini/gemini-1.5-flash",
auth_type="oauth2",
oauth_provider="google"
)
# Call LLM (OAuth2 token retrieved automatically)
response = await call_llm("What is the capital of France?", config)
print(response) # "The capital of France is Paris."
Using with @agent Decorator
from kagura import agent
from kagura.core.llm import LLMConfig
# Create OAuth2 config
gemini_config = LLMConfig(
model="gemini/gemini-1.5-flash",
auth_type="oauth2",
oauth_provider="google",
temperature=0.7
)
@agent(
name="translator",
template="Translate '{{ text }}' to {{ language }}",
llm_config=gemini_config
)
def translate(text: str, language: str) -> str:
pass
# Use the agent
result = translate("Hello", "Japanese")
print(result) # "こんにちは"
Switching Between API Key and OAuth2
You can use both authentication methods in the same project:
from kagura.core.llm import LLMConfig
# OpenAI with API key (uses OPENAI_API_KEY env var)
openai_config = LLMConfig(
model="gpt-4o-mini",
auth_type="api_key" # default
)
# Gemini with OAuth2
gemini_config = LLMConfig(
model="gemini/gemini-1.5-flash",
auth_type="oauth2",
oauth_provider="google"
)
CLI Commands
Login
Authenticate with Google OAuth2:
Options:
- --provider: OAuth2 provider (default: google)
Logout
Remove stored credentials:
Output:
Status
Check authentication status:
Possible outputs:
Authenticated:
Not Authenticated:
Security
Credential Storage
OAuth2 credentials are stored securely:
- Location:
~/.config/kagura/credentials.json.enc - Encryption: Fernet (AES-128 in CBC mode)
- Key Storage:
~/.config/kagura/.key(with 0600 permissions) - File Permissions: Both files have 0600 (owner read/write only)
Token Refresh
Access tokens are automatically refreshed:
- Automatic: Tokens are checked before each API call
- Transparent: Refresh happens automatically when expired
- Secure: Refresh tokens are encrypted and stored locally
Best Practices
- Never commit
~/.config/kagura/directory to version control - Keep
client_secrets.jsonsecure - it's like a password - Don't share your
credentials.json.encfile - Logout when you're done on shared machines
- Regenerate OAuth client ID if credentials are compromised
Troubleshooting
"Client secrets file not found"
Error:
Solution:
1. Download OAuth 2.0 Client ID JSON from Google Cloud Console
2. Save it as ~/.config/kagura/client_secrets.json
"Not authenticated with google"
Error:
NotAuthenticatedError: Not authenticated with google. Please run: kagura auth login --provider google
Solution:
Run kagura auth login --provider google to authenticate.
"Token refresh failed"
Error:
Solution:
1. Logout: kagura auth logout --provider google
2. Login again: kagura auth login --provider google
"Invalid credentials"
Error:
Possible causes: - Corrupted credentials file - Encryption key was regenerated
Solution:
1. Remove credentials: rm ~/.config/kagura/credentials.json.enc
2. Login again: kagura auth login --provider google
Environment Variables
OAuth2 authentication does NOT use environment variables. All authentication is handled through the OAuth2 flow and stored encrypted credentials.
If you prefer to use API keys instead:
# For Gemini (using API key)
export GOOGLE_API_KEY="your-api-key"
# Then use api_key auth type (default)
config = LLMConfig(model="gemini/gemini-1.5-flash")
Comparison: OAuth2 vs API Key
| Feature | OAuth2 | API Key |
|---|---|---|
| Supported LLMs | Google/Gemini only | All LLMs (OpenAI, Claude, Gemini) |
| Setup Complexity | Complex (Google Cloud Console setup required) | Simple (just get API key) |
| Security | OAuth2 tokens (short-lived, auto-refresh) | Long-lived API keys |
| Use Case | Multi-user apps, production with strict access control | Personal development, prototyping, CI/CD |
| Recommended For | Advanced users with specific needs | Most users (recommended) |
| Expiration | Auto-refresh | Manual rotation |
| Revocation | Can revoke from Google Console | Delete/regenerate key |
When to Use API Key (Recommended)
✅ Use API Key if: - You're doing personal development or prototyping - You want quick and simple setup - You're using Claude or OpenAI (OAuth2 not supported) - You're running in CI/CD pipelines - You're building single-user applications
How to get API Keys: - Gemini: Google AI Studio (fastest way!) - Claude: Anthropic Console - OpenAI: OpenAI Platform
When to Use OAuth2 (Advanced)
⚠️ Use OAuth2 only if: - You're building a multi-user application - Each user needs their own Google account authentication - You need strict per-user quota management - You have specific security requirements - You're comfortable with Google Cloud Console setup
Note: OAuth2 is only available for Google/Gemini.
Advanced Configuration
Custom Client Secrets Path
If you want to store client_secrets.json in a custom location:
from kagura.auth import OAuth2Manager, AuthConfig
from pathlib import Path
# Custom config
config = AuthConfig(
provider="google",
client_secrets_path=Path("/custom/path/client_secrets.json")
)
# Use custom config
auth = OAuth2Manager(config=config)
auth.login()
Custom Scopes
The default scopes are:
- https://www.googleapis.com/auth/generative-language
- openid
To use custom scopes:
from kagura.auth import OAuth2Manager, AuthConfig
config = AuthConfig(
provider="google",
scopes=[
"https://www.googleapis.com/auth/generative-language",
"openid",
"https://www.googleapis.com/auth/userinfo.email"
]
)
auth = OAuth2Manager(config=config)
Next Steps
- Learn about Agent Routing
- Explore Memory Management
- Try MCP Integration