authentication-patterns

athola's avatarfrom athola

Authentication patterns for external services: API keys, OAuth, token management, verification.Triggers: authentication, API keys, OAuth, token management, credentialsUse when: integrating external services or implementing authentication flows

⭐83stars🔀11forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for implementing and managing authentication patterns when integrating with external services. It standardizes secure credential handling for API keys, OAuth, and session tokens, featuring automated verification, interactive shell-based authentication, and robust error-recovery strategies to ensure seamless and secure agentic workflows.

Use Cases

  • 1. Secure API Integration: Streamlining the connection to external platforms like GitHub, AWS, or Gemini by automatically verifying API keys and environment variables before execution.
  • 2. Interactive OAuth Orchestration: Managing complex browser-based authentication flows and token caching for services that require user-level permissions and session persistence.
  • 3. Automated Credential Health Checks: Implementing proactive smoke tests and environment audits to detect expired tokens or missing credentials, preventing workflow interruptions.
  • 4. Multi-Service Workflow Management: Enabling agents to securely navigate and authenticate across multiple third-party platforms simultaneously using consistent, reusable patterns.
nameauthentication-patterns
description|
Triggersauthentication, API keys, OAuth, token management, credentials
Authentication patterns for external servicesAPI keys, OAuth, token management, verification.
Use whenintegrating external services or implementing authentication flows
categoryinfrastructure
tags[authentication, api-keys, oauth, tokens, security]
dependencies[error-patterns]
infrastructure[authentication, credential-management, auth-verification]
patterns[api-key-auth, oauth-flow, token-refresh]
complexitybeginner
estimated_tokens400
progressive_loadingtrue

Table of Contents

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

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