@kairosai/identity

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

Installation

npm install @kairosai/identity
# or
yarn add @kairosai/identity
# or
pnpm add @kairosai/identity

Quick start

import { KairosIdentity } from '@kairosai/identity'

const kairos = new KairosIdentity({
  apiKey: 'ki_your_api_key_here',
})

Get your API key from the KairosAI Identity dashboard.

Usage

Register an agent

const agent = await kairos.agents.register({
  name: 'My Email Agent',
  description: 'Reads and summarizes emails',
  capabilities: ['read:email', 'browse:web'],
  signingKeyPub: `-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----`,
})

console.log(agent.did)   // did:kairos:abc123xyz
console.log(agent.token) // eyJhbGc... — store as AGENT_TOKEN in your agent's .env

Important: Store the token in your agent's environment variables:

AGENT_TOKEN=eyJhbGciOiJFUzI1NiJ9...

Your agent sends this on every request to services that verify it. It won't be shown again.

Verify an agent

The core method. Call this before granting any agent access to a resource.

// The agent sends its token (stored as AGENT_TOKEN in its .env)
// Your service reads it from the incoming request header
const agentJwt = req.headers['x-agent-token'] // process.env.AGENT_TOKEN on the agent side

const result = await kairos.verify({
  token: agentJwt,
  targetResource: 'email-service',
  scopesRequested: ['read:email'],
})

if (!result.allowed) {
  console.log(result.decision) // 'DENIED' | 'REVOKED' | 'EXPIRED'
  console.log(result.reason)   // 'Agent lacks required scopes: read:email'
  throw new Error('Agent not authorized')
}

console.log(result.agent.did)          // did:kairos:abc123xyz
console.log(result.agent.activeScopes) // ['read:email', 'browse:web']

verifyOrThrow — one-liner gate

// Throws KairosError if not allowed — agent is guaranteed non-null
const agent = await kairos.verifyOrThrow({
  token: agentJwt,
  scopesRequested: ['read:email'],
})

// Safe to proceed — agent is verified
console.log(agent.activeScopes)

Revoke an agent

await kairos.agents.revoke('did:kairos:abc123xyz', {
  reason: 'compromised',
  notes: 'Private key was exposed in a log file',
})

// All future verify() calls for this agent will return { allowed: false, decision: 'REVOKED' }

Manage scopes

// Grant new scopes
await kairos.agents.updateScopes('did:kairos:abc123xyz', {
  grant: [
    { scope: 'write:calendar' },
    { scope: 'read:files', expiresAt: '2025-12-31T00:00:00Z' },
  ],
})

// Revoke specific scopes
await kairos.agents.updateScopes('did:kairos:abc123xyz', {
  revoke: ['browse:web'],
})

// Grant and revoke in one call
await kairos.agents.updateScopes('did:kairos:abc123xyz', {
  grant: [{ scope: 'read:database' }],
  revoke: ['execute:code'],
})

Fetch audit log

const log = await kairos.agents.auditLog('did:kairos:abc123xyz', {
  decision: 'DENIED',
  since: '2025-01-01T00:00:00Z',
  limit: 50,
})

console.log(log.pagination.total) // Total events matching filter
log.entries.forEach((entry) => {
  console.log(entry.eventType)  // 'AGENT_DENIED'
  console.log(entry.reason)     // 'Agent lacks required scopes'
  console.log(entry.entryHash)  // SHA-256 hash chain entry
})

Error handling

import { KairosIdentity, KairosError } from '@kairosai/identity'

try {
  const result = await kairos.verify({ token: agentJwt })
} catch (err) {
  if (err instanceof KairosError) {
    console.log(err.code)    // 'UNAUTHORIZED' | 'NOT_FOUND' | 'TIMEOUT' etc.
    console.log(err.status)  // HTTP status code
    console.log(err.message) // Human-readable error message
  }
}

Configuration

const kairos = new KairosIdentity({
  apiKey: 'ki_...',

  // Point to your own instance (default: https://identity.kairosaistudio.com)
  baseUrl: 'https://identity.yourdomain.com',

  // Request timeout in ms (default: 10000)
  timeout: 5000,
})

Available scopes

| Scope | Risk | Description | |-------|------|-------------| | read:email | medium | Read email messages | | write:email | high | Send emails | | read:calendar | low | Read calendar events | | write:calendar | medium | Create/edit calendar events | | read:files | medium | Read files and documents | | write:files | high | Create and edit files | | browse:web | low | Fetch public web pages | | submit:forms | high | Submit web forms | | execute:code | high | Run code in sandbox | | read:database | high | Query a database | | call:agents | medium | Invoke other agents | | read:identity | low | Verify other agents |

TypeScript

The SDK is written in TypeScript and ships full type definitions. All params and responses are fully typed.

import type {
  RegisterAgentParams,
  VerifyResponse,
  AuditEntry,
  KairosConfig,
} from '@kairosai/identity'

License

MIT © KairosAI