0
# Authentication & Sessions
1

2
GitHub3.py provides comprehensive authentication support for various authentication methods including personal access tokens, OAuth, username/password combinations, two-factor authentication, and GitHub Apps authentication.
3

4
## Capabilities
5

6
### Basic Authentication
7

8
Simple authentication using personal access tokens (recommended) or username/password combinations.
9

10
```python { .api }
11
def login(username=None, password=None, token=None, two_factor_callback=None):
12
    """
13
    Construct and return an authenticated GitHub session.
14
    
15
    Args:
16
        username (str, optional): GitHub username
17
        password (str, optional): Password for username/password auth
18
        token (str, optional): Personal access token (recommended)
19
        two_factor_callback (callable, optional): Function to provide 2FA codes
20
        
21
    Returns:
22
        GitHub: Authenticated GitHub client instance or None
23
    """
24

25
def enterprise_login(username=None, password=None, token=None, url=None, two_factor_callback=None):
26
    """
27
    Construct and return an authenticated GitHub Enterprise session.
28
    
29
    Args:
30
        username (str, optional): GitHub username
31
        password (str, optional): Password for username/password auth  
32
        token (str, optional): Personal access token
33
        url (str): GitHub Enterprise instance URL (required)
34
        two_factor_callback (callable, optional): Function to provide 2FA codes
35
        
36
    Returns:
37
        GitHubEnterprise: Authenticated GitHub Enterprise client or None
38
    """
39
```
40

41
**Usage Examples:**
42

43
```python
44
import github3
45

46
# Token authentication (recommended)
47
gh = github3.login(token='ghp_xxxxxxxxxxxxxxxxxxxx')
48

49
# Username + token authentication
50
gh = github3.login('username', token='ghp_xxxxxxxxxxxxxxxxxxxx')
51

52
# Username + password (not recommended, use tokens instead)
53
gh = github3.login('username', 'password')
54

55
# Enterprise authentication
56
gh = github3.enterprise_login(
57
    token='ghp_xxxxxxxxxxxxxxxxxxxx',
58
    url='https://github.company.com'
59
)
60
```
61

62
### GitHub Client Classes
63

64
Main client classes for authenticated and anonymous access to GitHub API.
65

66
```python { .api }
67
class GitHub:
68
    """Main GitHub API client class."""
69
    
70
    def __init__(self, username="", password="", token="", session=None):
71
        """
72
        Create a new GitHub instance.
73
        
74
        Args:
75
            username (str): Username for authentication
76
            password (str): Password for authentication
77
            token (str): Personal access token for authentication
78
            session: Custom requests session object
79
        """
80

81
    def login(self, username=None, password=None, token=None, two_factor_callback=None):
82
        """
83
        Authenticate the GitHub session.
84
        
85
        Args:
86
            username (str, optional): GitHub username
87
            password (str, optional): Password
88
            token (str, optional): Personal access token
89
            two_factor_callback (callable, optional): 2FA callback function
90
            
91
        Returns:
92
            bool: True if authentication successful
93
        """
94

95
class GitHubEnterprise(GitHub):
96
    """GitHub Enterprise API client."""
97
    
98
    def __init__(self, url, username="", password="", token="", verify=True, session=None):
99
        """
100
        Create a new GitHub Enterprise instance.
101
        
102
        Args:
103
            url (str): GitHub Enterprise instance URL (required)
104
            username (str): Username for authentication
105
            password (str): Password for authentication
106
            token (str): Personal access token for authentication
107
            verify (bool): SSL certificate verification
108
            session: Custom requests session object
109
        """
110
```
111

112
### GitHub Apps Authentication
113

114
Authentication as GitHub Apps for building integrations and CI/CD systems.
115

116
```python { .api }
117
class GitHub:
118
    def login_as_app(self, private_key_pem, app_id, expire_in=600):
119
        """
120
        Authenticate as a GitHub App.
121
        
122
        Args:
123
            private_key_pem (str): Private key in PEM format
124
            app_id (int): GitHub App ID
125
            expire_in (int): Token expiration time in seconds
126
            
127
        Returns:
128
            bool: True if authentication successful
129
        """
130

131
    def login_as_app_installation(self, private_key_pem, app_id, installation_id):
132
        """
133
        Authenticate as a GitHub App installation.
134
        
135
        Args:
136
            private_key_pem (str): Private key in PEM format
137
            app_id (int): GitHub App ID
138
            installation_id (int): Installation ID
139
            
140
        Returns:
141
            bool: True if authentication successful
142
        """
143
```
144

145
**Usage Examples:**
146

147
```python
148
import github3
149

150
# Read private key from file
151
with open('private-key.pem', 'r') as key_file:
152
    private_key = key_file.read()
153

154
# Authenticate as GitHub App
155
gh = github3.GitHub()
156
gh.login_as_app(private_key, app_id=12345)
157

158
# Authenticate as App installation
159
gh.login_as_app_installation(private_key, app_id=12345, installation_id=67890)
160
```
161

162
### Two-Factor Authentication
163

164
Support for two-factor authentication with callback functions.
165

166
```python { .api }
167
def two_factor_callback():
168
    """
169
    Callback function interface for 2FA authentication.
170
    
171
    Returns:
172
        str: Six-digit 2FA code
173
    """
174
```
175

176
**Usage Example:**
177

178
```python
179
import github3
180

181
def get_2fa_code():
182
    """Prompt user for 2FA code."""
183
    return input("Enter 2FA code: ")
184

185
# Login with 2FA callback
186
gh = github3.login('username', 'password', two_factor_callback=get_2fa_code)
187
```
188

189
### Session Management
190

191
Custom session handling with authentication state and rate limiting.
192

193
```python { .api }
194
class GitHubSession:
195
    """Custom requests session with GitHub-specific features."""
196

197
class BasicAuth:
198
    """Basic authentication handler."""
199

200
class TokenAuth:
201
    """Token authentication handler."""
202

203
class AppBearerTokenAuth:
204
    """App bearer token authentication."""
205

206
class AppInstallationTokenAuth:
207
    """App installation token authentication."""
208
```
209

210
### Authentication Decorators
211

212
Decorators for methods requiring specific authentication types.
213

214
```python { .api }
215
def requires_auth(func):
216
    """Decorator requiring any form of authentication."""
217

218
def requires_basic_auth(func):
219
    """Decorator requiring username/password authentication."""
220

221
def requires_app_credentials(func):  
222
    """Decorator requiring client credentials."""
223

224
def requires_app_bearer_auth(func):
225
    """Decorator requiring app bearer token."""
226

227
def requires_app_installation_auth(func):
228
    """Decorator requiring app installation token."""
229
```
230

231
## Authentication Exceptions
232

233
```python { .api }
234
class AuthenticationFailed(GitHubError):
235
    """HTTP 401 Unauthorized - Invalid credentials."""
236

237
class GeneratedTokenExpired(GitHubError):
238
    """Generated token has expired."""
239

240
class AppInstallationTokenExpired(GeneratedTokenExpired):
241
    """App installation token expired."""
242

243
class AppTokenExpired(GeneratedTokenExpired):
244
    """App token expired."""
245

246
class MissingAppAuthentication(GitHubError):
247
    """Missing app authentication."""
248
```