Skip to content

Register now for

# 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.

Methods:

Name | Description
--- | ---
`authenticate` | Attempt to authenticate with the server using either id_token or API key.
`auth_with_cookies` | Attempt to fetch authentication via cookies and set id_token.
`get_auth_header` | Get the authentication header for making API requests.
`request_api_key` | Prompt the user to input their API key.

Examples:

Initialize Auth with an API key

    >>> auth = Auth(api_key="your_api_key_here")

Initialize Auth without API key (will prompt for input)

    >>> auth = Auth()

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`

    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
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    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("_", 1)[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`

    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    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`

    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    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.
        """
        import requests  # scoped as slow import

        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`

    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    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.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`max_attempts` | `int` | Maximum number of authentication attempts. | `3`

Returns:

Type | Description
--- | ---
`bool` | True if authentication is successful, False otherwise.

Source code in `ultralytics/hub/auth.py`

     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    def request_api_key(self, max_attempts: int = 3) -> bool:
        """
        Prompt the user to input their API key.

        Args:
            max_attempts (int): Maximum number of authentication attempts.

        Returns:
            (bool): True if authentication is successful, False otherwise.
        """
        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("_", 1)[0]  # remove model id if present
            if self.authenticate():
                return True
        raise ConnectionError(emojis(f"{PREFIX}Failed to authenticate ❌"))

📅 Created 1 year ago ✏️ Updated 1 year ago