API Reference

Complete reference for the GitHub OAuth Helper Python API.

Overview

The GitHub OAuth Helper provides both a programmatic API and a command-line interface for handling GitHub OAuth authentication flows.

Core Classes

GitHubOAuth

The main class for handling GitHub OAuth operations.

from gh_oauth_helper import GitHubOAuth, GitHubOAuthError

Constructor

GitHubOAuth(
    client_id: Optional[str] = None,
    client_secret: Optional[str] = None, 
    redirect_uri: Optional[str] = None,
    secure_mode: bool = False
)

Parameters:

client_id (str, optional): GitHub OAuth app client ID. If not provided, reads from GITHUB_CLIENT_ID environment variable.
client_secret (str, optional): GitHub OAuth app client secret. If not provided, reads from GITHUB_CLIENT_SECRET environment variable.
redirect_uri (str, optional): OAuth redirect URI. If not provided, reads from GITHUB_REDIRECT_URI environment variable or defaults to http://localhost:8080/callback.
secure_mode (bool): If True, enforces HTTPS for non-localhost redirect URIs.

Raises:

GitHubOAuthError: If required credentials are missing.

Example:

# Using environment variables
oauth = GitHubOAuth()

# Using explicit credentials
oauth = GitHubOAuth(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="http://localhost:8080/callback",
    secure_mode=True
)

Methods

`generate_authorization_url(scopes=None, state=None)`

Generate the GitHub authorization URL for the OAuth flow.

Parameters:

scopes (List[str], optional): List of OAuth scopes to request. Defaults to ["user:email", "repo"].
state (str, optional): CSRF protection state parameter. If not provided, a secure random state is generated.

Returns:

Tuple[str, str]: A tuple containing the authorization URL and the state parameter.

Example:

auth_url, state = oauth.generate_authorization_url(
    scopes=["user", "public_repo", "read:org"]
)
print(f"Visit: {auth_url}")
print(f"State: {state}")  # Save this for verification

`exchange_code_for_token(code, state=None)`

Exchange an authorization code for an access token.

Parameters:

code (str): The authorization code received from GitHub’s callback.
state (str, optional): The state parameter for CSRF verification.

Returns:

Dict[str, Any]: Dictionary containing token information including access_token, token_type, and scope.

Raises:

GitHubOAuthError: If the code exchange fails or state verification fails.

Example:

try:
    # Traditional method: extract code manually
    token_data = oauth.exchange_code_for_token(
        code="ghu_1234567890abcdef",
        state="abc123"  # From generate_authorization_url
    )
    access_token = token_data["access_token"]
    print(f"Token received: {access_token[:10]}...")
    
    # Note: For easier flows, consider using the CLI's paste-the-URL method
    # See OAUTH_FLOW_GUIDE.md for details
except GitHubOAuthError as e:
    print(f"Token exchange failed: {e}")

`test_api_access(access_token)`

Test API access with the provided access token.

Parameters:

access_token (str): The GitHub access token to test.

Returns:

Dict[str, Any]: Dictionary containing authenticated user information.

Raises:

GitHubOAuthError: If the token is invalid or API access fails.

Example:

try:
    user_info = oauth.test_api_access(access_token)
    print(f"Authenticated as: {user_info['login']}")
    print(f"Name: {user_info.get('name', 'N/A')}")
    print(f"Email: {user_info.get('email', 'N/A')}")
except GitHubOAuthError as e:
    print(f"Token validation failed: {e}")

`revoke_token(access_token)`

Revoke an access token.

Parameters:

access_token (str): The GitHub access token to revoke.

Returns:

bool: True if revocation was successful, False otherwise.

Example:

success = oauth.revoke_token(access_token)
if success:
    print("Token revoked successfully")
else:
    print("Token revocation failed")

Convenience Functions

For simple use cases, the library provides convenience functions that use environment variables.

`start_auth_flow(oauth_helper=None, scopes=None)`

Start an OAuth flow using environment variables.

Parameters:

oauth_helper (GitHubOAuth, optional): OAuth helper instance. If not provided, creates one using environment variables.
scopes (List[str], optional): OAuth scopes to request.

Returns:

Tuple[str, str]: Authorization URL and state parameter.

Example:

from gh_oauth_helper import start_auth_flow

auth_url, state = start_auth_flow(scopes=["user", "repo"])
print(f"Visit: {auth_url}")

`complete_auth_flow(code, oauth_helper=None, state=None)`

Complete an OAuth flow by exchanging code for token.

Parameters:

code (str): Authorization code from GitHub.
oauth_helper (GitHubOAuth, optional): OAuth helper instance.
state (str, optional): State parameter for verification.

Returns:

Dict[str, Any]: Token data from GitHub.

Example:

from gh_oauth_helper import complete_auth_flow

# Traditional code exchange method
token_data = complete_auth_flow(code="ghu_123", state="abc123")
access_token = token_data["access_token"]

# For easier flows, see the CLI's paste-the-URL method in OAUTH_FLOW_GUIDE.md

`verify_token(access_token, oauth_helper=None)`

Verify an access token by testing API access.

Parameters:

access_token (str): Token to verify.
oauth_helper (GitHubOAuth, optional): OAuth helper instance.

Returns:

Dict[str, Any]: User information from GitHub API.

Example:

from gh_oauth_helper import verify_token

user_info = verify_token(access_token)
print(f"Token valid for user: {user_info['login']}")

Exceptions

GitHubOAuthError

Base exception class for OAuth-related errors.

class GitHubOAuthError(Exception):
    """Exception raised for GitHub OAuth errors."""
    pass

Common scenarios:

Missing credentials
Invalid authorization codes
Expired tokens
Network errors
API rate limiting

Example:

from gh_oauth_helper import GitHubOAuthError

try:
    oauth = GitHubOAuth()
    # ... OAuth operations
except GitHubOAuthError as e:
    print(f"OAuth error: {e}")
    # Handle OAuth-specific errors
except Exception as e:
    print(f"Unexpected error: {e}")
    # Handle other errors

Environment Variables

The library supports the following environment variables:

Variable	Description	Required	Default
`GITHUB_CLIENT_ID`	OAuth app client ID	Yes	None
`GITHUB_CLIENT_SECRET`	OAuth app client secret	Yes	None
`GITHUB_REDIRECT_URI`	OAuth callback URL	No	`http://localhost:8080/callback`

Setting environment variables:

# Linux/macOS
export GITHUB_CLIENT_ID="your_client_id"
export GITHUB_CLIENT_SECRET="your_client_secret"
export GITHUB_REDIRECT_URI="http://localhost:8080/callback"

# Windows (Command Prompt)
set GITHUB_CLIENT_ID=your_client_id
set GITHUB_CLIENT_SECRET=your_client_secret

# Windows (PowerShell)
$env:GITHUB_CLIENT_ID="your_client_id"
$env:GITHUB_CLIENT_SECRET="your_client_secret"

OAuth Scopes Reference

Common GitHub OAuth scopes:

User Scopes

user - Read user profile information
user:email - Read user email addresses
user:follow - Follow/unfollow other users

Repository Scopes

repo - Full access to repositories (public and private)
public_repo - Access to public repositories only
repo:status - Access to commit status
repo_deployment - Access to deployment status

Organization Scopes

read:org - Read organization membership
write:org - Write access to organization membership
admin:org - Full organization access

Other Scopes

gist - Create and modify gists
notifications - Access notifications
read:discussion - Read team discussions
workflow - Access to GitHub Actions workflows

Example with multiple scopes:

oauth = GitHubOAuth()
auth_url, state = oauth.generate_authorization_url(
    scopes=["user", "repo", "read:org", "gist"]
)

Type Hints

The library includes comprehensive type hints for better IDE support:

from typing import Dict, List, Optional, Tuple, Any
from gh_oauth_helper import GitHubOAuth

oauth: GitHubOAuth = GitHubOAuth()
auth_url: str
state: str
auth_url, state = oauth.generate_authorization_url()

token_data: Dict[str, Any] = oauth.exchange_code_for_token(code)
user_info: Dict[str, Any] = oauth.test_api_access(token_data["access_token"])

Error Handling Best Practices

import logging
from gh_oauth_helper import GitHubOAuth, GitHubOAuthError

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def handle_oauth_flow(code: str, state: str) -> Optional[str]:
    """Handle OAuth flow with proper error handling."""
    try:
        oauth = GitHubOAuth()
        
        # Exchange code for token
        token_data = oauth.exchange_code_for_token(code, state)
        access_token = token_data["access_token"]
        
        # Verify token works
        user_info = oauth.test_api_access(access_token)
        logger.info(f"Successfully authenticated user: {user_info['login']}")
        
        return access_token
        
    except GitHubOAuthError as e:
        logger.error(f"OAuth error: {e}")
        return None
    except Exception as e:
        logger.error(f"Unexpected error: {e}")
        return None

Advanced Usage

Custom HTTP Session

import requests
from gh_oauth_helper.core import GitHubOAuth

# Create custom session with timeouts and retries
session = requests.Session()
session.timeout = 30

# Note: Advanced session customization requires modifying the core class
# This is an example of how you might extend the functionality

Batch Operations

def authenticate_multiple_users(codes_and_states):
    """Authenticate multiple users in batch."""
    oauth = GitHubOAuth()
    results = []
    
    for code, state in codes_and_states:
        try:
            token_data = oauth.exchange_code_for_token(code, state)
            user_info = oauth.test_api_access(token_data["access_token"])
            results.append({
                "success": True,
                "user": user_info["login"],
                "token": token_data["access_token"]
            })
        except GitHubOAuthError as e:
            results.append({
                "success": False,
                "error": str(e)
            })
    
    return results

Security Considerations

When using the API programmatically:

Never log sensitive data: Tokens and secrets should never appear in logs
Use secure storage: Store tokens securely (environment variables, key stores)
Implement token rotation: Refresh tokens when possible
Validate inputs: Always validate and sanitize user inputs
Use HTTPS: Ensure all OAuth flows use HTTPS in production
Handle errors gracefully: Don’t expose sensitive error details to users

def secure_token_storage(access_token: str) -> None:
    """Example of secure token handling."""
    # DON'T: Log the full token
    # logger.info(f"Received token: {access_token}")
    
    # DO: Log only partial information
    logger.info(f"Received token: {access_token[:10]}...")
    
    # DO: Store securely (example with environment variable)
    import os
    os.environ["USER_GITHUB_TOKEN"] = access_token

API Reference

Overview

Core Classes

GitHubOAuth

Constructor

Methods

generate_authorization_url(scopes=None, state=None)

exchange_code_for_token(code, state=None)

test_api_access(access_token)

revoke_token(access_token)

Convenience Functions

start_auth_flow(oauth_helper=None, scopes=None)

complete_auth_flow(code, oauth_helper=None, state=None)

verify_token(access_token, oauth_helper=None)

Exceptions

GitHubOAuthError

Environment Variables

OAuth Scopes Reference

User Scopes

Repository Scopes

Organization Scopes

Other Scopes

Type Hints

Error Handling Best Practices

Advanced Usage

Custom HTTP Session

Batch Operations

Security Considerations

`generate_authorization_url(scopes=None, state=None)`

`exchange_code_for_token(code, state=None)`

`test_api_access(access_token)`

`revoke_token(access_token)`

`start_auth_flow(oauth_helper=None, scopes=None)`

`complete_auth_flow(code, oauth_helper=None, state=None)`

`verify_token(access_token, oauth_helper=None)`