Merge pull request #41 from cogsol/40-feature-improve-credentials-experience-in-the-framework

fix: improve API key error messages and add tests for credential checks

Author: agustin-anastasia

README.md

@@ -118,11 +118,13 @@ agents/salesagent/
 
 ### 3. Configure Environment
 
-Copy `.env.example` to `.env` and set your API credentials:
+To use CogSol you need API credentials. Visit **[https://onboarding.cogsol.ai](https://onboarding.cogsol.ai)** to obtain your credentials. Make sure to also configure the service API key in the implantation portal before running any commands.
+
+Copy `.env.example` to `.env` and fill in the credentials obtained from the portal:
 
 ```env
 COGSOL_ENV=development
-COGSOL_API_KEY=your-api-key
+COGSOL_API_KEY=your-api-key  # Obtain from https://onboarding.cogsol.ai
 # Optional: Azure AD B2C client credentials for JWT
 # If not provided, the Auth will be skipped
 COGSOL_AUTH_CLIENT_ID=your-client-id
@@ -690,17 +692,14 @@ from cogsol.content import BaseRetrieval, ReorderingStrategy
 
 ### Environment Variables
 
+Credentials are obtained from the CogSol onboarding portal at **[https://onboarding.cogsol.ai](https://onboarding.cogsol.ai)**. Configure your service API key there before running migrations or using the CLI.
+
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `COGSOL_API_KEY` | Yes | API Key authentication |
+| `COGSOL_API_KEY` | Yes | Service API key — obtain from the portal at https://onboarding.cogsol.ai |
 | `COGSOL_ENV` | No | Environment name (e.g., `local`, `development`, `production`) |
-| `COGSOL_AUTH_CLIENT_ID` | No | Client Id provided for adminitrators |
-| `COGSOL_AUTH_SECRET` | No | Auth Secret provided for adminitrators |
-
-# Optional: Azure AD B2C client credentials for JWT\
-# If not provided, the Auth will be skipped
-COGSOL_AUTH_CLIENT_ID=your-client-id
-COGSOL_AUTH_SECRET=your-client-secret
+| `COGSOL_AUTH_CLIENT_ID` | No | Client Id provided for administrators |
+| `COGSOL_AUTH_SECRET` | No | Auth secret provided for administrators |
 
 ### Project Settings (`settings.py`)
 

cogsol/core/api.py

@@ -134,7 +134,11 @@ def _refresh_bearer_token(self) -> None:
         client_secret = os.environ.get("COGSOL_AUTH_SECRET")
 
         if not client_secret:
-            raise CogSolAPIError("Missing authentication configuration: COGSOL_AUTH_SECRET")
+            raise CogSolAPIError(
+                "Missing authentication configuration: COGSOL_AUTH_SECRET is not set.\n"
+                "To obtain your credentials, visit https://onboarding.cogsol.ai\n"
+                "and configure the service API key in the implantation portal."
+            )
 
         authority = "https://pyxiscognitivesweden.b2clogin.com/pyxiscognitivesweden.onmicrosoft.com/B2C_1A_CS_signup_signin_Sweden_MigrationOIDC"
         scopes = [f"https://pyxiscognitivesweden.onmicrosoft.com/{client_id}/.default"]

cogsol/management/commands/chat.py

@@ -319,8 +319,16 @@ def handle(self, project_path: Path | None, **options: Any) -> int:
 
         api_base = get_cognitive_api_base_url()
         api_key = os.environ.get("COGSOL_API_KEY")
-        if not api_base:
-            print_error("COGSOL_API_BASE is required in .env to chat with CogSol.")
+        if not api_key and not os.environ.get("COGSOL_AUTH_CLIENT_ID"):
+            print_error(
+                "No API credentials found.\n"
+                "Set COGSOL_API_KEY in your .env file to authenticate with the CogSol API.\n"
+                "\n"
+                "To obtain your credentials:\n"
+                "  1. Visit https://onboarding.cogsol.ai\n"
+                "  2. Configure the service API key in the implantation portal\n"
+                "  3. Copy the key to COGSOL_API_KEY in your .env file"
+            )
             return 1
 
         remote_ids = self._load_remote_ids(project_path, app)

cogsol/management/commands/importagent.py

@@ -296,8 +296,16 @@ def handle(self, project_path: Path | None, **options: Any) -> int:
         api_base = get_cognitive_api_base_url()
         api_key = os.environ.get("COGSOL_API_KEY")
         content_base = get_content_api_base_url() or api_base
-        if not api_base:
-            print("COGSOL_API_BASE is required in .env to import.")
+        if not api_key and not os.environ.get("COGSOL_AUTH_CLIENT_ID"):
+            print(
+                "Error: No API credentials found.\n"
+                "Set COGSOL_API_KEY in your .env file to authenticate with the CogSol API.\n"
+                "\n"
+                "To obtain your credentials:\n"
+                "  1. Visit https://onboarding.cogsol.ai\n"
+                "  2. Configure the service API key in the implantation portal\n"
+                "  3. Copy the key to COGSOL_API_KEY in your .env file"
+            )
             return 1
 
         client = CogSolClient(api_base, api_key=api_key, content_base_url=content_base)

cogsol/management/commands/migrate.py

@@ -58,8 +58,16 @@ def handle(self, project_path: Path | None, **options: Any) -> int:
         api_base = get_cognitive_api_base_url()
         api_key = self._env("COGSOL_API_KEY", required=False)
         content_base = get_content_api_base_url()
-        if not api_base:
-            print("COGSOL_API_BASE is required in .env to run migrations against CogSol APIs.")
+        if not api_key and not os.environ.get("COGSOL_AUTH_CLIENT_ID"):
+            print(
+                "Error: No API credentials found.\n"
+                "Set COGSOL_API_KEY in your .env file to authenticate with the CogSol API.\n"
+                "\n"
+                "To obtain your credentials:\n"
+                "  1. Visit https://onboarding.cogsol.ai\n"
+                "  2. Configure the service API key in the implantation portal\n"
+                "  3. Copy the key to COGSOL_API_KEY in your .env file"
+            )
             return 1
 
         exit_code = 0