kairosai-identity 0.1.0

Official Python SDK for the KairosAI Identity platform

kairosai-identity

Official Python SDK for the KairosAI Identity platform — AI agent identity, permissioning, and tamper-evident audit.

Installation

pip install kairosai-identity

Quick start

from kairosai_identity import KairosIdentity

kairos = KairosIdentity(api_key="ki_your_api_key_here")

Get your API key from the KairosAI Identity dashboard.

---

Usage

Register an agent

agent = kairos.agents.register(
    name="My Email Agent",
    description="Reads and summarizes emails",
    capabilities=["read:email", "browse:web"],
    signing_key_pub="""-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----""",
)

print(agent.did)   # did:kairos:abc123xyz
print(agent.token) # eyJhbGc... — save this in your env vars!

Important: Store agent.token in your agent's environment variables (e.g. AGENT_TOKEN). It won't be shown again.

---

Verify an agent

result = kairos.verify(
    token=agent_jwt,               # from os.environ["AGENT_TOKEN"]
    target_resource="email-service",
    scopes_requested=["read:email"],
)

if not result.allowed:
    print(result.decision)  # 'DENIED' | 'REVOKED' | 'EXPIRED'
    print(result.reason)    # 'Agent lacks required scopes: read:email'
    raise PermissionError("Agent not authorized")

print(result.agent.did)           # did:kairos:abc123xyz
print(result.agent.active_scopes) # ['read:email', 'browse:web']

verify_or_raise — one-liner gate

# Raises KairosVerificationError if not allowed
agent = kairos.verify_or_raise(
    token=agent_jwt,
    scopes_requested=["read:email"],
)

# Safe to proceed — agent is verified
print(agent.active_scopes)

---

Revoke an agent

kairos.agents.revoke(
    "did:kairos:abc123xyz",
    reason="compromised",
    notes="Private key was exposed in a log file",
)

# All future verify() calls for this agent return allowed=False

---

Manage scopes

# Grant new scopes
kairos.agents.update_scopes(
    "did:kairos:abc123xyz",
    grant=[
        {"scope": "write:calendar"},
        {"scope": "read:files", "expires_at": "2025-12-31T00:00:00Z"},
    ],
)

# Revoke specific scopes
kairos.agents.update_scopes(
    "did:kairos:abc123xyz",
    revoke=["browse:web"],
)

---

Fetch audit log

log = kairos.agents.audit_log(
    "did:kairos:abc123xyz",
    decision="DENIED",
    limit=50,
)

print(log.pagination.total)  # Total matching events
for entry in log.entries:
    print(entry.event_type)  # 'AGENT_DENIED'
    print(entry.reason)      # 'Agent lacks required scopes'
    print(entry.entry_hash)  # SHA-256 hash chain entry

---

Batch verify

results = kairos.batch_verify([
    {"token": jwt1, "scopes_requested": ["read:email"]},
    {"token": jwt2, "scopes_requested": ["browse:web"]},
])

print(results.summary.allowed)  # 1
print(results.summary.denied)   # 1

for result in results.results:
    print(result.allowed, result.decision)

---

Async usage

Full async support via AsyncKairosIdentity — uses httpx.AsyncClient under the hood.

import asyncio
from kairosai_identity import AsyncKairosIdentity

async def main():
    async with AsyncKairosIdentity(api_key="ki_...") as kairos:
        result = await kairos.verify(token=agent_jwt)
        if not result.allowed:
            raise PermissionError("Agent not authorized")

        agent = result.agent
        print(agent.did)

asyncio.run(main())

FastAPI integration

from fastapi import FastAPI, Header, HTTPException, Depends
from kairosai_identity import AsyncKairosIdentity, KairosVerificationError
import os

app = FastAPI()
kairos = AsyncKairosIdentity(api_key=os.environ["KAIROS_API_KEY"])

async def require_agent(x_agent_token: str = Header(...)):
    try:
        return await kairos.verify_or_raise(
            token=x_agent_token,
            scopes_requested=["read:data"],
        )
    except KairosVerificationError as e:
        raise HTTPException(status_code=403, detail=str(e))

@app.get("/api/data")
async def get_data(agent=Depends(require_agent)):
    return {"data": "...", "verified_agent": agent.did}

---

Error handling

from kairosai_identity import (
    KairosIdentity,
    KairosError,
    KairosAuthError,
    KairosNotFoundError,
    KairosVerificationError,
    KairosTimeoutError,
)

try:
    result = kairos.verify(token=agent_jwt)
except KairosAuthError:
    print("Invalid API key")
except KairosTimeoutError:
    print("Request timed out")
except KairosError as e:
    print(f"Error {e.code} ({e.status}): {e}")

---

Configuration

kairos = KairosIdentity(
    api_key="ki_...",

    # Point to your own instance (default: https://identity.kairosaistudio.com)
    base_url="https://identity.yourdomain.com",

    # Request timeout in seconds (default: 10.0)
    timeout=5.0,
)

---

Requirements

• Python 3.9+
• httpx >= 0.24.0

---

License

MIT © KairosAI