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

setup.cfg

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

upcloud_api/cloud_manager/__init__.py

@@ -10,6 +10,7 @@
 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
 
 
 class CloudManager(
@@ -31,21 +32,17 @@ 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.parse(username, password, token)
 
         self.api = API(
-            token=f'Basic {encoded_credentials}',
+            token=credentials.authorization,
             timeout=timeout,
         )
 

upcloud_api/credentials.py

@@ -0,0 +1,102 @@
+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):]
+
+        try:
+            return base64.b64decode(value).decode()
+        except:
+            raise UpCloudClientError(f"Invalid keyring value: {value}")
+
+    return value
+
+
+def _read_keyring_value(username: str) -> str:
+    if keyring is None:
+        return None
+
+    value = keyring.get_password(KEYRING_SERVICE_NAME, username)
+    return _parse_keyring_value(value) if value else None
+
+class Credentials:
+    """
+    Class for handling UpCloud API credentials.
+    """
+
+    def __init__(self, username: str = None, password: str = None, token: str = None):
+        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 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})')

upcloud_api/ip_address.py

@@ -18,6 +18,7 @@ class IPAddress(UpCloudResource):
 
     Note that all of the fields are not always available depending on the API call,
     consult the official API docs for details.
+
     """
 
     ATTRIBUTES = {

upcloud_api/tag.py

@@ -12,6 +12,7 @@ class Tag(UpCloudResource):
     description -- optional description
     servers -- list of Server objects (with only uuid populated)
                can be instantiated with UUID strings or Server objects
+
     """
 
     ATTRIBUTES = {'name': None, 'description': None, 'servers': []}