Certificate Verification

Overview

Any system in the world can verify whether a Kakunin certificate is currently valid by calling one public endpoint — no API key required.

GET https://api.kakunin.ai/v1/verify/:serial

This is Kakunin's equivalent of OCSP (Online Certificate Status Protocol) — the same mechanism browsers use to check whether a website's TLS certificate has been revoked.

Response

{
  "data": {
    "serial_number": "abc123def456",
    "status": "active",
    "valid": true,
    "issued_at": "2026-01-15T09:00:00Z",
    "expires_at": "2027-01-15T09:00:00Z",
    "agent": {
      "id": "uuid",
      "name": "trading-bot-prod",
      "model": "gpt-4o",
      "version": "2026-01-15"
    }
  }
}

Valid vs. Invalid

Caching

Responses are CDN-cached to reduce latency at scale:

When a certificate is revoked, Kakunin emits a certificate.revoked webhook event so that SDK consumers can invalidate their local cache immediately — without waiting for TTL expiry.

How to Use It

Direct API call

curl https://api.kakunin.ai/v1/verify/abc123def456

No Authorization header required.

With the @kakunin/verify SDK (coming soon)

The SDK wraps the verify endpoint with local caching, real-time revocation webhook handling, and a one-line enforcement middleware for Node.js/Express API gateways:

import { kakunin } from '@kakunin/verify'

app.use(kakunin.requireVerified({
  onFailure: 'reject',
  cacheSeconds: 300,
  header: 'x-kakunin-cert-serial',
}))

See SDKs for full details.

How Agents Present Their Certificate

Agents include their Kakunin cert serial in every outgoing request using a standard header:

X-Kakunin-Cert-Serial: <serial_number>
X-Kakunin-Tenant-Id: <tenant_id>

The receiving system's gateway reads this header and calls the verify endpoint to enforce authorization.

Kong Gateway AI Agent mTLS Verification

For enterprise deployments, you can enforce security directly at the API gateway border. By configuring Kong Gateway AI Agent mTLS Verification, the gateway handles the cryptographic handshake and certificate verification before any requests reach your downstream microservices.

Kong configuration steps:

1. Configure a Kong client-certificate verification plugin to enforce mutual TLS (mTLS) using the Kakunin CA certificate as the trusted root.
2. Extract the agent's certificate serial number from the client certificate.
3. Pass the serial number downstream in the X-Kakunin-Cert-Serial header or perform real-time verification against the Kakunin verify API.

This pattern offloads certificate verification latency and ensures that non-compliant agents are rejected at the edge.

Rate Limiting

The verify endpoint is rate-limited by IP: 100 requests per 60 seconds. For high-throughput enforcement, use the SDK's local cache to avoid per-request network calls.