Skip to content

Reference for ultralytics/hub/auth.py

Note

This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/hub/auth.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!


ultralytics.hub.auth.Auth 

Auth(api_key: str = '', verbose: bool = False)

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

Enable verbose logging.

 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 

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

authenticate 

authenticate() -> bool

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_auth_header 

get_auth_header()

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 

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 ❌"))



📅 Created 1 year ago ✏️ Updated 6 months ago
jk4e glenn-jocher Burhan-Q