feat: add support for tokens and system keyring

Author: kangasta

CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Support authentication with API tokens
+- Added `Credentials` class for parsing credentials from environment similarly than in our Go based tooling.
+
 ## [2.7.0] - 2025-07-23
 
 ### Changed

README.md

@@ -44,6 +44,16 @@ python setup.py install
 More usage examples are available under [docs/]. If there's a specific thing you're interested in,
 but are not able to get working, please [contact UpCloud support](https://upcloud.com/contact/).
 
+### Load credentials from environment
+
+```python
+from upcloud_api import CloudManager, Credentials
+
+credentials = Credentials.parse()
+c = CloudManager(**credentials.dict)
+c.get_account()
+```
+
 ### Defining and creating servers
 
 ```python

setup.cfg

@@ -20,3 +20,7 @@ install_requires =
 packages =
     upcloud_api
     upcloud_api.cloud_manager
+
+[options.extras_require]
+keyring =
+    keyring>=23.0

upcloud_api/__init__.py

@@ -11,6 +11,7 @@
 __copyright__ = 'Copyright (c) 2015 UpCloud Oy'
 
 from upcloud_api.cloud_manager import CloudManager
+from upcloud_api.credentials import Credentials
 from upcloud_api.errors import UpCloudAPIError, UpCloudClientError
 from upcloud_api.firewall import FirewallRule
 from upcloud_api.host import Host

upcloud_api/cloud_manager/__init__.py

@@ -1,5 +1,3 @@
-import base64
-
 from upcloud_api.api import API
 from upcloud_api.cloud_manager.firewall_mixin import FirewallManager
 from upcloud_api.cloud_manager.host_mixin import HostManager
@@ -10,6 +8,8 @@
 from upcloud_api.cloud_manager.server_mixin import ServerManager
 from upcloud_api.cloud_manager.storage_mixin import StorageManager
 from upcloud_api.cloud_manager.tag_mixin import TagManager
+from upcloud_api.credentials import Credentials
+from upcloud_api.errors import UpCloudClientError
 
 
 class CloudManager(
@@ -31,21 +31,23 @@ class CloudManager(
 
     api: API
 
-    def __init__(self, username: str, password: str, timeout: int = 60) -> None:
+    def __init__(
+        self, username: str = None, password: str = None, timeout: int = 60, token: str = None
+    ) -> None:
         """
         Initiates CloudManager that handles all HTTP connections with UpCloud's API.
 
         Optionally determine a timeout for API connections (in seconds). A timeout with the value
         `None` means that there is no timeout.
         """
-        if not username or not password:
-            raise Exception('Invalid credentials, please provide a username and password')
-
-        credentials = f'{username}:{password}'.encode()
-        encoded_credentials = base64.b64encode(credentials).decode()
+        credentials = Credentials(username, password, token)
+        if not credentials.is_defined:
+            raise UpCloudClientError(
+                "Credentials are not defined. Please provide username and password or an API token."
+            )
 
         self.api = API(
-            token=f'Basic {encoded_credentials}',
+            token=credentials.authorization,
             timeout=timeout,
         )
 

upcloud_api/credentials.py

@@ -0,0 +1,120 @@
+import base64
+import os
+
+try:
+    import keyring
+except ImportError:
+    keyring = None
+
+from upcloud_api.errors import UpCloudClientError
+
+ENV_KEY_USERNAME = "UPCLOUD_USERNAME"
+ENV_KEY_PASSWORD = "UPCLOUD_PASSWORD"  # noqa: S105
+ENV_KEY_TOKEN = "UPCLOUD_TOKEN"  # noqa: S105
+
+KEYRING_SERVICE_NAME = "UpCloud"
+KEYRING_TOKEN_USER = ""
+KEYRING_GO_PREFIX = "go-keyring-base64:"
+
+
+def _parse_keyring_value(value: str) -> str:
+    if value.startswith(KEYRING_GO_PREFIX):
+        value = value[len(KEYRING_GO_PREFIX) :]
+        return base64.b64decode(value).decode()
+
+    return value
+
+
+def _read_keyring_value(username: str) -> str:
+    if keyring is None:
+        return None
+
+    value = keyring.get_password(KEYRING_SERVICE_NAME, username)
+    try:
+        return _parse_keyring_value(value) if value else None
+    except Exception:
+        raise UpCloudClientError(
+            f"Failed to read keyring value for {username}. Ensure that the value saved to the system keyring is correct."
+        ) from None
+
+
+class Credentials:
+    """
+    Class for handling UpCloud API credentials.
+    """
+
+    def __init__(self, username: str = None, password: str = None, token: str = None):
+        """
+        Initializes the Credentials object with username, password and/or token. Use `parse` method to read credentials from environment variables or keyring.
+        """
+        self._username = username
+        self._password = password
+        self._token = token
+
+    @property
+    def authorization(self) -> str:
+        """
+        Returns the authorization header value based on the provided credentials.
+        """
+        if self._token:
+            return f"Bearer {self._token}"
+
+        credentials = f"{self._username}:{self._password}".encode()
+        encoded_credentials = base64.b64encode(credentials).decode()
+        return f"Basic {encoded_credentials}"
+
+    @property
+    def dict(self) -> dict:
+        """
+        Returns the credentials as a dictionary.
+        """
+        return {
+            "username": self._username,
+            "password": self._password,
+            "token": self._token,
+        }
+
+    @property
+    def is_defined(self) -> bool:
+        """
+        Checks if the credentials are defined.
+        """
+        return bool(self._username and self._password or self._token)
+
+    def _read_from_env(self):
+        if not self._username:
+            self._username = os.getenv(ENV_KEY_USERNAME)
+        if not self._password:
+            self._password = os.getenv(ENV_KEY_PASSWORD)
+        if not self._token:
+            self._token = os.getenv(ENV_KEY_TOKEN)
+
+    def _read_from_keyring(self):
+        if self._username and not self._password:
+            self._password = _read_keyring_value(self._username)
+
+        if self.is_defined:
+            return
+
+        self._token = _read_keyring_value(KEYRING_TOKEN_USER)
+
+    @classmethod
+    def parse(cls, username: str = None, password: str = None, token: str = None):
+        """
+        Parses credentials from the provided parameters, environment variables or the system keyring.
+        """
+        credentials = cls(username, password, token)
+        if credentials.is_defined:
+            return credentials
+
+        credentials._read_from_env()
+        if credentials.is_defined:
+            return credentials
+
+        credentials._read_from_keyring()
+        if credentials.is_defined:
+            return credentials
+
+        raise UpCloudClientError(
+            f"Credentials not found. These must be set in configuration, via environment variables or in the system keyring ({KEYRING_SERVICE_NAME})"
+        )