Manages authentication processes including API key handling, cookie-based authentication, and header generation.
The class supports different methods of authentication:
1. Directly using an API key.
2. Authenticating using browser cookies (specifically in Google Colab).
3. Prompting the user to enter an API key.
Attributes:
| Name |
Type |
Description |
id_token |
str | bool
|
Token used for identity verification, initialized as False.
|
api_key |
str | bool
|
API key for authentication, initialized as False.
|
model_key |
bool
|
Placeholder for model key, initialized as False.
|
Handles API key validation, Google Colab authentication, and new key requests. Updates SETTINGS upon successful
authentication.
Parameters:
| Name |
Type |
Description |
Default |
api_key
|
str
|
API key or combined key_id format.
|
''
|
verbose
|
bool
|
|
False
|
Source code in ultralytics/hub/auth.py
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71 | def __init__(self, api_key: str = "", verbose: bool = False):
"""
Initialize Auth class and authenticate user.
Handles API key validation, Google Colab authentication, and new key requests. Updates SETTINGS upon successful
authentication.
Args:
api_key (str): API key or combined key_id format.
verbose (bool): Enable verbose logging.
"""
# Split the input API key in case it contains a combined key_model and keep only the API key part
api_key = api_key.split("_")[0]
# Set API key attribute as value passed or SETTINGS API key if none passed
self.api_key = api_key or SETTINGS.get("api_key", "")
# If an API key is provided
if self.api_key:
# If the provided API key matches the API key in the SETTINGS
if self.api_key == SETTINGS.get("api_key"):
# Log that the user is already logged in
if verbose:
LOGGER.info(f"{PREFIX}Authenticated ✅")
return
else:
# Attempt to authenticate with the provided API key
success = self.authenticate()
# If the API key is not provided and the environment is a Google Colab notebook
elif IS_COLAB:
# Attempt to authenticate using browser cookies
success = self.auth_with_cookies()
else:
# Request an API key
success = self.request_api_key()
# Update SETTINGS with the new API key after successful authentication
if success:
SETTINGS.update({"api_key": self.api_key})
# Log that the new login was successful
if verbose:
LOGGER.info(f"{PREFIX}New authentication successful ✅")
elif verbose:
LOGGER.info(f"{PREFIX}Get API key from {API_KEY_URL} and then run 'yolo login API_KEY'")
|
auth_with_cookies() -> bool
Attempt to fetch authentication via cookies and set id_token.
User must be logged in to HUB and running in a supported browser.
Returns:
| Type |
Description |
bool
|
True if authentication is successful, False otherwise.
|
Source code in ultralytics/hub/auth.py
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124 | def auth_with_cookies(self) -> bool:
"""
Attempt to fetch authentication via cookies and set id_token.
User must be logged in to HUB and running in a supported browser.
Returns:
(bool): True if authentication is successful, False otherwise.
"""
if not IS_COLAB:
return False # Currently only works with Colab
try:
authn = request_with_credentials(f"{HUB_API_ROOT}/v1/auth/auto")
if authn.get("success", False):
self.id_token = authn.get("data", {}).get("idToken", None)
self.authenticate()
return True
raise ConnectionError("Unable to fetch browser authentication details.")
except ConnectionError:
self.id_token = False # reset invalid
return False
|
Attempt to authenticate with the server using either id_token or API key.
Returns:
| Type |
Description |
bool
|
True if authentication is successful, False otherwise.
|
Source code in ultralytics/hub/auth.py
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102 | def authenticate(self) -> bool:
"""
Attempt to authenticate with the server using either id_token or API key.
Returns:
(bool): True if authentication is successful, False otherwise.
"""
try:
if header := self.get_auth_header():
r = requests.post(f"{HUB_API_ROOT}/v1/auth", headers=header)
if not r.json().get("success", False):
raise ConnectionError("Unable to authenticate.")
return True
raise ConnectionError("User has not authenticated locally.")
except ConnectionError:
self.id_token = self.api_key = False # reset invalid
LOGGER.warning(f"{PREFIX}Invalid API key")
return False
|
Get the authentication header for making API requests.
Returns:
| Type |
Description |
dict | None
|
The authentication header if id_token or API key is set, None otherwise.
|
Source code in ultralytics/hub/auth.py
126
127
128
129
130
131
132
133
134
135
136 | def get_auth_header(self):
"""
Get the authentication header for making API requests.
Returns:
(dict | None): The authentication header if id_token or API key is set, None otherwise.
"""
if self.id_token:
return {"authorization": f"Bearer {self.id_token}"}
elif self.api_key:
return {"x-api-key": self.api_key}
|
request_api_key(max_attempts: int = 3) -> bool
Prompt the user to input their API key.
Source code in ultralytics/hub/auth.py
73
74
75
76
77
78
79
80
81
82
83 | def request_api_key(self, max_attempts: int = 3) -> bool:
"""Prompt the user to input their API key."""
import getpass
for attempts in range(max_attempts):
LOGGER.info(f"{PREFIX}Login. Attempt {attempts + 1} of {max_attempts}")
input_key = getpass.getpass(f"Enter API key from {API_KEY_URL} ")
self.api_key = input_key.split("_")[0] # remove model id if present
if self.authenticate():
return True
raise ConnectionError(emojis(f"{PREFIX}Failed to authenticate ❌"))
|
