0
# Authentication
1

2
Authentication capabilities for connecting to Google Sheets API using OAuth2 or service account credentials.
3

4
## Capabilities
5

6
### OAuth2 Authentication
7

8
Authenticate using OAuth2 credentials file for user-based access to Google Sheets.
9

10
```python { .api }
11
def authorize(client_secret='client_secret.json',
12
              service_account_file=None,
13
              service_account_env_var=None,
14
              service_account_json=None,
15
              credentials_directory='',
16
              scopes=_SCOPES,
17
              custom_credentials=None,
18
              local=False,
19
              **kwargs) -> Client:
20
    """
21
    Authenticate this application with a google account.
22
    
23
    Parameters:
24
    - client_secret (str): Location of the oauth2 credentials file
25
    - service_account_file (str): Location of a service account file
26
    - service_account_env_var (str): Environment variable containing service account credentials
27
    - service_account_json (str): Service account JSON string directly
28
    - credentials_directory (str): Location for token file storage. Use 'global' for OS-dependent global location
29
    - scopes (list): List of scopes for authentication. Defaults to Sheets and Drive API scopes
30
    - custom_credentials: Pre-configured credentials object
31
    - local (bool): Use local server for OAuth2 flow instead of console-based flow
32
    
33
    Returns:
34
    Client: Authenticated client instance for spreadsheet operations
35
    
36
    Raises:
37
    AuthenticationError: If authentication process fails
38
    """
39
```
40

41
### Service Account Authentication
42

43
Authenticate using service account credentials for server-to-server access.
44

45
```python
46
import pygsheets
47

48
# Using service account file
49
gc = pygsheets.authorize(service_account_file='path/to/service-account.json')
50

51
# Using environment variable
52
import os
53
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'path/to/service-account.json'
54
gc = pygsheets.authorize(service_account_env_var='GOOGLE_APPLICATION_CREDENTIALS')
55

56
# Using JSON string directly
57
service_account_json = '{"type": "service_account", ...}'
58
gc = pygsheets.authorize(service_account_json=service_account_json)
59
```
60

61
### OAuth2 User Authentication
62

63
Authenticate using OAuth2 for user-based access with consent flow.
64

65
```python
66
import pygsheets
67

68
# Standard OAuth2 flow (console-based)
69
gc = pygsheets.authorize(client_secret='client_secret.json')
70

71
# Local server OAuth2 flow
72
gc = pygsheets.authorize(client_secret='client_secret.json', local=True)
73

74
# Custom credentials directory
75
gc = pygsheets.authorize(
76
    client_secret='client_secret.json',
77
    credentials_directory='/path/to/credentials'
78
)
79

80
# Global credentials directory
81
gc = pygsheets.authorize(
82
    client_secret='client_secret.json',
83
    credentials_directory='global'
84
)
85
```
86

87
### Custom Scopes
88

89
Specify custom scopes for authentication based on required permissions.
90

91
```python
92
import pygsheets
93

94
# Custom scopes for read-only access
95
readonly_scopes = [
96
    'https://www.googleapis.com/auth/spreadsheets.readonly',
97
    'https://www.googleapis.com/auth/drive.readonly'
98
]
99

100
gc = pygsheets.authorize(
101
    client_secret='client_secret.json',
102
    scopes=readonly_scopes
103
)
104

105
# Full access scopes (default)
106
full_scopes = [
107
    'https://www.googleapis.com/auth/spreadsheets',
108
    'https://www.googleapis.com/auth/drive'
109
]
110

111
gc = pygsheets.authorize(
112
    client_secret='client_secret.json',
113
    scopes=full_scopes
114
)
115
```
116

117
## Types
118

119
### Client Class
120

121
```python { .api }
122
class Client:
123
    """
124
    Main interface for Google Sheets operations.
125
    
126
    Attributes:
127
    - credentials: Google API credentials object
128
    - service: Google Sheets API service instance
129
    - drive: Google Drive API service instance
130
    """
131
    
132
    def __init__(self, credentials, retries=3, seconds_per_quota=100):
133
        """
134
        Initialize client with credentials.
135
        
136
        Parameters:
137
        - credentials: Google API credentials
138
        - retries (int): Number of retry attempts for failed requests
139
        - seconds_per_quota (int): Seconds to wait between quota-limited requests
140
        """
141
```
142

143
### Authentication Exceptions
144

145
```python { .api }
146
class AuthenticationError(PyGsheetsException):
147
    """Raised when authentication process fails."""
148
    pass
149
```