0
# Application Default Credentials
1

2
Automatically detects and loads the most appropriate credentials for the current environment, following Google Cloud's standard credential discovery flow. This is the recommended approach for most applications as it works seamlessly across development, testing, and production environments.
3

4
## Capabilities
5

6
### Default Credential Discovery
7

8
Automatically discovers credentials using Google Cloud's standard Application Default Credentials (ADC) flow, checking sources in order: environment variable, user credentials, service account, Compute Engine metadata.
9

10
```python { .api }
11
def default(
12
    scopes=None,
13
    request=None,
14
    quota_project_id=None,
15
    default_scopes=None
16
):
17
    """
18
    Construct credentials from Application Default Credentials.
19
    
20
    Args:
21
        scopes (Sequence[str]): The list of scopes for the credentials. If specified,
22
            the credentials will automatically be scoped if necessary.
23
        request (google.auth.transport.Request): An object used to make HTTP requests.
24
            This is used to determine the associated project ID for external account
25
            credentials. If not specified, then it will use a default HTTP transport.
26
        quota_project_id (str): The project ID used for quota and billing.
27
            This project may be different from the project used to create the credentials.
28
        default_scopes (Sequence[str]): Default scopes passed by a Google client library.
29
            Use 'scopes' for user-defined scopes.
30
        
31
    Returns:
32
        Tuple[google.auth.credentials.Credentials, Optional[str]]: The constructed
33
            credentials and the project ID. The project ID is the
34
            quota_project_id if provided, or the default project ID if available.
35
            
36
    Raises:
37
        google.auth.exceptions.DefaultCredentialsError: If no credentials could
38
            be found or if the credentials found are not valid.
39
    """
40
```
41

42
Usage example:
43

44
```python
45
import google.auth
46

47
# Basic usage - discover credentials automatically
48
credentials, project = google.auth.default()
49

50
# With specific scopes
51
credentials, project = google.auth.default(
52
    scopes=['https://www.googleapis.com/auth/cloud-platform']
53
)
54

55
# With quota project
56
credentials, project = google.auth.default(
57
    scopes=['https://www.googleapis.com/auth/bigquery'],
58
    quota_project_id='my-billing-project'
59
)
60
```
61

62
### Loading from File
63

64
Loads credentials from a JSON credentials file, supporting service account keys, authorized user credentials, external account credentials, and impersonated service account credentials.
65

66
```python { .api }
67
def load_credentials_from_file(
68
    filename,
69
    scopes=None,
70
    default_scopes=None,
71
    quota_project_id=None,
72
    request=None
73
):
74
    """
75
    Load Google credentials from a file.
76
    
77
    The credentials file must be a service account key, stored authorized
78
    user credentials, external account credentials, or impersonated service
79
    account credentials.
80
    
81
    Args:
82
        filename (str): The full path to the credentials file.
83
        scopes (Sequence[str]): The list of scopes for the credentials. If
84
            specified, the credentials will automatically be scoped if necessary.
85
        default_scopes (Sequence[str]): Default scopes passed by a Google client
86
            library. Use 'scopes' for user-defined scopes.
87
        quota_project_id (str): The project ID used for quota and billing.
88
        request (google.auth.transport.Request): An object used to make HTTP
89
            requests. This is used to determine the associated project ID for
90
            external account credentials. If not specified, then it will use a
91
            default HTTP transport.
92
            
93
    Returns:
94
        Tuple[google.auth.credentials.Credentials, Optional[str]]: Loaded
95
            credentials and the project ID. Authorized user credentials do not
96
            have the project ID information. External account credentials project
97
            IDs may not always be determined.
98
            
99
    Raises:
100
        google.auth.exceptions.DefaultCredentialsError: if the file is in the
101
            wrong format or is missing.
102
    """
103
```
104

105
Usage example:
106

107
```python
108
import google.auth
109

110
# Load from service account file
111
credentials, project = google.auth.load_credentials_from_file(
112
    '/path/to/service-account.json',
113
    scopes=['https://www.googleapis.com/auth/cloud-platform']
114
)
115

116
# Load from authorized user file
117
credentials, project = google.auth.load_credentials_from_file(
118
    '/path/to/authorized-user.json'
119
)
120
```
121

122
### Loading from Dictionary
123

124
Loads credentials from a dictionary containing credential information, useful when credentials are stored in configuration systems or loaded from non-file sources.
125

126
```python { .api }
127
def load_credentials_from_dict(
128
    info,
129
    scopes=None,
130
    default_scopes=None,
131
    quota_project_id=None,
132
    request=None
133
):
134
    """
135
    Load Google credentials from a dictionary.
136
    
137
    The credentials dictionary must contain information for service account
138
    credentials, authorized user credentials, external account credentials,
139
    or impersonated service account credentials.
140
    
141
    Args:
142
        info (Mapping[str, str]): The credential information dictionary.
143
        scopes (Sequence[str]): The list of scopes for the credentials. If
144
            specified, the credentials will automatically be scoped if necessary.
145
        default_scopes (Sequence[str]): Default scopes passed by a Google client
146
            library. Use 'scopes' for user-defined scopes.
147
        quota_project_id (str): The project ID used for quota and billing.
148
        request (google.auth.transport.Request): An object used to make HTTP
149
            requests. This is used to determine the associated project ID for
150
            external account credentials. If not specified, then it will use a
151
            default HTTP transport.
152
            
153
    Returns:
154
        Tuple[google.auth.credentials.Credentials, Optional[str]]: Loaded
155
            credentials and the project ID. Authorized user credentials do not
156
            have the project ID information. External account credentials project
157
            IDs may not always be determined.
158
            
159
    Raises:
160
        google.auth.exceptions.DefaultCredentialsError: if the info is not in the
161
            expected format.
162
    """
163
```
164

165
Usage example:
166

167
```python
168
import google.auth
169
import json
170

171
# Load from dictionary (e.g., from environment or config)
172
with open('/path/to/credentials.json') as f:
173
    creds_info = json.load(f)
174

175
credentials, project = google.auth.load_credentials_from_dict(
176
    creds_info,
177
    scopes=['https://www.googleapis.com/auth/cloud-platform']
178
)
179
```
180

181
## Environment Variables
182

183
```python { .api }
184
# Environment variables used by default credential discovery
185
GOOGLE_APPLICATION_CREDENTIALS: str  # Path to service account JSON file
186
GOOGLE_CLOUD_PROJECT: str           # Default project ID  
187
GCLOUD_PROJECT: str                 # Alternative project ID variable
188
GOOGLE_CLOUD_QUOTA_PROJECT: str     # Default quota project ID
189
```
190

191
## Credential Discovery Flow
192

193
The `default()` function follows this discovery order:
194

195
1. **GOOGLE_APPLICATION_CREDENTIALS environment variable** - Points to service account JSON file
196
2. **gcloud user credentials** - From `gcloud auth application-default login`
197
3. **gcloud service account** - From `gcloud auth activate-service-account`
198
4. **Cloud SDK attached service account** - When running on Google Cloud
199
5. **Compute Engine metadata service** - When running on Compute Engine, App Engine, etc.
200

201
## Error Handling
202

203
```python { .api }
204
class DefaultCredentialsError(google.auth.exceptions.GoogleAuthError):
205
    """Raised when default credentials cannot be determined or loaded."""
206
```
207

208
Common scenarios that raise `DefaultCredentialsError`:
209
- No credentials found in any discovery source
210
- Credentials file is malformed or missing
211
- Network issues accessing metadata service
212
- Invalid scopes for the credential type