En quoi KYA diffère-t-il des outils IAM classiques ?

L'IAM traditionnel (Auth0, Okta) est conçu pour des humains qui se connectent. Les agents IA fonctionnent différemment: ils agissent en continu, de façon autonome et à vitesse machine. KYA est conçu spécifiquement pour l'identité des agents, avec des tokens de capacité à durée limitée, une vérification au niveau de l'action, et des signatures cryptographiques sur chaque requête.

Puis-je héberger KYA moi-même ?

Oui. KYA est entièrement open-source (Apache 2.0) et livré avec un setup Docker Compose. Vous pouvez exécuter la stack complète (API + PostgreSQL + Redis) sur votre propre infrastructure en quelques minutes.

Quelle latence ajoute l'endpoint /verify ?

L'endpoint /verify vise une latence p99 inférieure à 20ms en auto-hébergement. KYA supporte également un mode de vérification local avec un cache de politiques Redis qui élimine entièrement le saut réseau.

Comment fonctionne la révocation ?

La révocation d'agent est immédiate. En quelques secondes, tous les appels verify suivants pour cet agent retournent REFUSER. La révocation de capacité (pour les JWTs en vol) utilise une liste noire Redis avec TTL correspondant. Sans attente d'expiration du token.

Quels langages de programmation sont supportés ?

KYA est livré avec des SDKs officiels pour JavaScript/TypeScript (@kya/sdk-js) et Python (@kya/sdk-python). Les deux incluent la génération de clés Ed25519, la sérialisation JSON canonique et des clients API typés. L'API REST fonctionne avec n'importe quel langage.

Le journal d'audit est-il vraiment inviolable ?

Oui. Chaque workspace maintient une chaîne de hachage SHA-256 sur ses événements d'audit. Toute modification d'événements historiques casse la chaîne et est immédiatement détectable. Cette conception satisfait les exigences de preuve d'inviolabilité pour les audits SOC2 et ISO 27001.

Quickstart

Run your first ALLOW + DENY decision in under 5 minutes.

Goal: start the KYA reference implementation and see one ALLOW + one DENY decision.

Prerequisites#

Docker Desktop (running)
Python 3.12+
make
Node.js 18+ (for JS examples)

Step 1 — Install & start services#

terminal

# Clone the repo
git clone https://github.com/qurveai/know-your-agent
cd kya

# Install dependencies
make install

# Copy env template
cp apps/api/.env.example apps/api/.env

# Generate Ed25519 keypair (paste output into .env)
make generate-dev-keypair

# Start API + Postgres + Redis
docker compose up -d
make migrate-up
make dev

The API is now running at http://localhost:8000. Swagger UI available at http://localhost:8000/docs.

Playground (UI)#

The repository ships apps/playground — a local UI to test all API flows without writing code. Useful for exploring the API before integrating.

terminal

# From the repo root (API must be running)
pnpm install

# Generate TS types from the OpenAPI snapshot (CI-safe, default)
pnpm --filter playground types:api

# Or generate from a live running API
OPENAPI_SOURCE=url pnpm --filter playground types:api

# Start the playground UI
pnpm --filter playground dev

Re-run types:api after any API schema change to keep playground request/response types aligned.

Step 2 — Run the ALLOW demo#

terminal

cd examples/reference-implementation
make demo-allow

Expected output:

✅ workspace created
✅ agent registered
✅ policy bound
✅ capability issued
✅ verify = ALLOW
✅ action executed

Step 3 — Run the DENY demo#

terminal

make demo-deny

Expected output:

✅ verify = DENY (reason=SPEND_LIMIT_EXCEEDED)

Protect a Purchase in 5 Minutes#

Try the e-commerce example to see KYA integrated into a real purchase flow:

terminal

cd examples/purchase-target
cp .env.example .env
# Add your bootstrap token to KYA_BOOTSTRAP_TOKEN
npm install
npm run dev

# In a second terminal:
set -a; source .env; set +a
npm run demo

Troubleshooting#

Error	Fix
connection refused	Services not ready — run make up and wait 10–20s
WORKSPACE_BOOTSTRAP_DISABLED	API missing bootstrap token in .env
SIGNATURE_INVALID	Payload/signature mismatch — check canonicalization
POLICY_NOT_BOUND	Setup flow interrupted before policy bind — restart demo

# Inspect running services
docker compose ps

Edit this page on GitHub →