Auth & credentials

What this solves

Long-lived credentials (API keys, HTTP Basic passwords, OAuth client secrets) should not be modeled as regular agent inputs in prompts. The platform provides an Auth tab in the agent editor, JSON fields auth_methods and auth_config, and a small runtime SDK on the worker: ViksaAuth and ViksaAuthError (from the injected ViksaAI module).

Authoring in the UI

1. Open the agent, then the Auth (or Data & access → auth) step.
2. Declare one or more auth methods (e.g. bearer token, API key, HTTP Basic) with the parameters you need.
3. Map each secret to vault storage or a placeholder; method ids and param names must be stable— they become environment keys method_id.param_name at run time.
4. When using Generate with AI, the model is instructed to emit auth_methods / auth_config when the prompt implies credentials.

In Python (main.py)

Endpoints stay async and take a single payload: Dict[str, Any]. For secrets, read from the SDK instead of the payload where possible.

from typing import Dict, Any
from .ViksaAI import mcp_endpoint, ViksaAuth, ViksaAuthError

@mcp_endpoint(description="Example call with configured auth")
async def do_call(payload: Dict[str, Any]):
    token = ViksaAuth.require_param("bearer", "api_key")
    # Use token in aiohttp/httpx headers — never log the raw value.
    return {"ok": True}

get_param and require_param read resolved values. preferred_method / require_method help when the agent supports multiple ways to authenticate.

How it maps to the worker

At deploy time, the platform materializes only fully resolved auth methods: partial configuration is omitted so the agent fails clearly instead of running half-configured. Enabled method ids are exposed in VIKSA_AUTH_ENABLED_METHODS (see Secrets for storage and rotation practices).