Observatory

The Observatory at auth.kanoniv.com is the hosted control plane for Kanoniv Auth. It provides agent registration, delegation management, scope enforcement, reputation scoring, and a full provenance trail.

Getting Started

Sign Up

Create an account at auth.kanoniv.com or via CLI/SDK.

CLI

kt signup

Python

from kanoniv_auth.cloud import TrustClient

trust = TrustClient(url="https://auth.kanoniv.com")
trust.signup("[email protected]", "password", "Your Name")

Get Your API Key

Login returns an API key. Save it - it is shown once.

CLI

kt login

Python

result = trust.login("[email protected]", "password")
api_key = result["api_key"]

The CLI saves the key to ~/.kanoniv/cloud.key automatically. You can also set the KT_API_KEY environment variable.

Connect

from kanoniv_auth.cloud import TrustClient

trust = TrustClient(api_key="kt_live_...", url="https://auth.kanoniv.com")

The default URL is https://trust.kanoniv.com. Pass url explicitly if your deployment uses a different hostname.

Agent Registry

Register agents with capabilities and auto-generated DIDs.

Python

trust.register("coordinator", capabilities=["resolve", "merge", "delegate"], description="Orchestration agent")
trust.register("sdr-agent", capabilities=["resolve", "search"], description="Sales development")

agents = trust.agents()            # List all, sorted by reputation
agent = trust.agent("sdr-agent")   # Details + RL context

CLI

kt register coordinator -c resolve,merge,delegate
kt register sdr-agent -c resolve,search
kt agents

Each agent gets a persistent did:agent: identifier. The DID is auto-generated from the agent name and a random suffix. Re-registering an existing agent name updates capabilities and sets status to online.

Delegation Management

Grant scoped authority between agents.

Python

trust.delegate(
    from_agent="coordinator",
    to_agent="sdr-agent",
    scopes=["resolve", "search"],
    expires_in_hours=4,
    metadata={"max_amount": 100}
)

delegations = trust.delegations("sdr-agent")
trust.revoke(delegation_id)

CLI

kt delegate coordinator sdr-agent -s resolve,search
kt delegations sdr-agent
kt revoke <delegation-id>

The delegation response includes the delegatee's RL context (outcome history and summary) so the caller can assess the agent's track record before granting authority.

Enforcement

The Observatory enforces delegation scopes on every provenance entry. When an agent records an action via POST /v1/provenance, the server checks:

1. Scope check - Does the agent have an active delegation granting the action scope?
2. Caveat check - Does the action metadata satisfy delegation caveats (e.g. max_amount)?
3. Expiry check - Is the delegation still within its TTL?

Check	Pass	Fail
Scope	Action proceeds with status ALLOWED	403 delegation_denied
Caveat	Action proceeds	403 caveat_exceeded
Expiry	Action proceeds	403 delegation_expired
No delegation	-	403 no_delegation

Blocked actions are still recorded in the provenance trail with status BLOCKED and a reason code. Denied attempts are evidence too.

INFO

The observatory agent and agents identified in the X-Agent-Name header as system bypass enforcement. All other agents must have an active delegation.

Recording Actions

# This action is enforced - sdr-agent must have "resolve" scope
trust.action("sdr-agent", "resolve", metadata={"entity": "[email protected]"})

# This would be blocked - no "merge" scope
trust.action("sdr-agent", "merge", metadata={"entities": ["e1", "e2"]})
# Returns {"error": "delegation_denied", "reason": "..."}

Every successful action also auto-records an outcome memory entry and updates the agent's reputation.

Reputation Scoring

Every agent builds a reputation score from 0 to 100 based on five weighted signals:

Signal	Weight	Calculation
Activity	30%	log2(total_actions + 1) * 15, capped at 100
Success Rate	25%	successes / (successes + failures) * 100
Reward Signal	20%	Average feedback score (-1 to 1), normalized to 0-100
Tenure	15%	days_registered / 90 * 100, capped at 100
Action Diversity	10%	distinct_action_types / 7 * 100

Submit feedback to affect reputation:

trust.feedback(agent_did, "resolve", "success", reward_signal=0.8, content="Accurate match")

Reputation is recomputed after every feedback submission and after every auto-recorded outcome.

WARNING

Reputation scores below 20 trigger a warning in the dashboard. This does not block actions automatically, but operators can configure delegation policies that require minimum reputation thresholds.

Memory

Agents can memorize decisions, investigations, and patterns.

trust.memorize("sdr-agent", "Resolved [email protected] to entity e3a1f9c2", entry_type="decision")
entries = trust.memories(entry_type="decision", author="agent:sdr-agent")

INFO

The author field uses the format agent:{name}. When querying memories by author, include the agent: prefix.

Memory entry types: decision, investigation, pattern, knowledge, task, outcome.

Recall retrieves all outcomes and a summary for a specific agent DID:

context = trust.recall(agent_did)
# Returns: {"did": "...", "summary": {...}, "entries": [...]}

Reputation Trends

View time-series reputation data for charts and monitoring:

trend = trust.trend(agent_did, window="7d")
# Returns: {"did": "...", "window": "7d", "bucket": "day", "points": [...]}

trend_24h = trust.trend(agent_did, window="24h")
# Returns hourly buckets

Each point contains time, total, successes, failures, and avg_reward.

Dashboard

The Observatory web UI at auth.kanoniv.com shows:

• Agent Registry - All agents with status (online/idle/offline), capabilities, and reputation scores. Agents go idle after 5 minutes without activity and offline after 1 hour.
• Delegation Management - Active delegations with scopes, caveats, and expiry. Grant and revoke from the UI.
• Provenance Trail - Chronological timeline of every action with ALLOWED/BLOCKED status and metadata.
• Reputation Trends - Time-series charts (7-day and 24-hour windows) showing success rates and reward signals.
• Memory - Agent decisions and knowledge entries with expandable detail cards.

Plans

Plan	Agents	Actions/month	Delegations
Free	3	100	5
Team	25	10,000	100
Enterprise	Unlimited	Unlimited	Unlimited

API Reference

Method	Path	Purpose
POST	/v1/agents/register	Register or update agent
GET	/v1/agents	List agents (sorted by reputation)
GET	/v1/agents/:name	Agent details + RL context
POST	/v1/delegations	Grant delegation
GET	/v1/delegations	List delegations (filter by agent_name)
PUT	/v1/delegations/:id	Update delegation scopes
DELETE	/v1/delegations/:id	Revoke delegation
POST	/v1/provenance	Record action (enforced)
GET	/v1/provenance	List provenance entries
POST	/v1/memory	Save memory entry
GET	/v1/memory	List memory entries (filter by entry_type, author)
PUT	/v1/memory/:id	Update memory entry
POST	/v1/memory/feedback	Submit feedback (triggers reputation recompute)
GET	/v1/memory/recall	Agent RL context + outcomes for a DID
GET	/v1/memory/trend	Reputation time-series (7d or 24h windows)
POST	/v1/auth/signup	Create account
POST	/v1/auth/login	Get API key
GET	/v1/auth/me	Current tenant info and usage
DELETE	/v1/auth/reset	Wipe data (keeps account)
DELETE	/v1/auth/account	Delete everything

INFO

Auth endpoints (/v1/auth/*) are served through the control plane proxy. Agent, delegation, provenance, and memory endpoints are served by the Observatory API directly.

Next Steps

• Claude Code Skills - Five skills with scope enforcement
• wrap-mcp - MCP proxy for any server
• Reputation - Reputation scoring deep dive
• Kanoniv Auth - Back to overview