Table of Contents
-
Overview
-
When to Use
-
Authentication Methods
-
Quick Start
-
Verify Authentication
-
Smoke Test
-
Standard Flow
-
Step 1: Check Environment
-
Step 2: Verify with Service
-
Step 3: Handle Failures
-
Integration Pattern
-
Detailed Resources
-
Exit Criteria
Authentication Patterns
Overview
Common authentication patterns for integrating with external services. Provides consistent approaches to credential management, verification, and error handling.
When To Use
-
Integrating with external APIs
-
Need credential verification
-
Managing multiple auth methods
-
Handling auth failures gracefully
When NOT To Use
-
Project doesn't use the leyline infrastructure patterns
-
Simple scripts without service architecture needs
Authentication Methods
Method Best For Environment Variable
API Key Simple integrations {SERVICE}_API_KEY
OAuth User-authenticated Browser-based flow
Token Session-based {SERVICE}_TOKEN
None Public APIs N/A
Quick Start
Verify Authentication
from leyline.auth import verify_auth, AuthMethod
API Key verification
status = verify_auth( service="gemini", method=AuthMethod.API_KEY, env_var="GEMINI_API_KEY" )
if not status.authenticated: print(f"Auth failed: {status.message}") print(f"Action: {status.suggested_action}")
Verification: Run the command with --help flag to verify availability.
Smoke Test
def verify_with_smoke_test(service: str) -> bool: """Verify auth with simple request.""" result = execute_simple_request(service, "ping") return result.success
Verification: Run pytest -v to verify tests pass.
Standard Flow
Step 1: Check Environment
def check_credentials(service: str, env_var: str) -> bool: value = os.getenv(env_var) if not value: print(f"Missing {env_var}") return False return True
Verification: Run the command with --help flag to verify availability.
Step 2: Verify with Service
def verify_with_service(service: str) -> AuthStatus: result = subprocess.run( [service, "auth", "status"], capture_output=True ) return AuthStatus( authenticated=(result.returncode == 0), message=result.stdout.decode() )
Verification: Run the command with --help flag to verify availability.
Step 3: Handle Failures
def handle_auth_failure(service: str, method: AuthMethod) -> str: actions = { AuthMethod.API_KEY: f"Set {service.upper()}_API_KEY environment variable", AuthMethod.OAUTH: f"Run '{service} auth login' for browser auth", AuthMethod.TOKEN: f"Refresh token with '{service} token refresh'" } return actions[method]
Verification: Run the command with --help flag to verify availability.
Integration Pattern
In your skill's frontmatter
dependencies: [leyline:authentication-patterns]
Verification: Run the command with --help flag to verify availability.
Interactive Authentication (Shell)
For workflows requiring interactive authentication with token caching and session management:
Source the interactive auth script
source plugins/leyline/scripts/interactive_auth.sh
Ensure authentication before proceeding
ensure_auth github || exit 1 ensure_auth gitlab || exit 1 ensure_auth aws || exit 1
Continue with authenticated operations
gh pr view 123 glab issue list aws s3 ls
Features:
-
✅ Interactive OAuth flows for GitHub, GitLab, AWS, and more
-
✅ Token caching (5-minute TTL)
-
✅ Session persistence (24-hour TTL)
-
✅ CI/CD compatible (auto-detects non-interactive environments)
-
✅ Multi-service support
See modules/interactive-auth.md for complete documentation.
Detailed Resources
-
Auth Methods: See modules/auth-methods.md for method details
-
Verification: See modules/verification-patterns.md for testing patterns
-
Interactive: See modules/interactive-auth.md for shell-based auth flows
Exit Criteria
-
Credentials verified or clear failure message
-
Suggested action for auth failures
-
Smoke test confirms working auth
Troubleshooting
Common Issues
Command not found Ensure all dependencies are installed and in PATH
Permission errors Check file permissions and run with appropriate privileges
Unexpected behavior Enable verbose logging with --verbose flag