Integration

How to add AAP to your API and agents.

Part 1: aap-guard (API / server)

Verify X-AAP-Assertion and X-AAP-Signature on your Express API.

1. Install

npm install aap-guard express

2. Wire up the guard

const express = require('express');
const { aapGuard } = require('aap-guard');

const app = express();
app.use(express.json());

// getAgent: fetch agent from your registry
const getAgent = async (agentId) => {
  const res = await fetch(`${REGISTRY_URL}/agents/${agentId}`);
  if (!res.ok) return null;
  const a = await res.json();
  return { agentId: a.agentId, publicKey: a.publicKeyBase64, status: 'active',
    allowedIntents: a.allowedIntents, allowedAudiences: a.allowedAudiences };
};

// nonceStore: prevent replay (use Redis in production)
const nonces = new Map();
const nonceStore = {
  checkAndSet: async (act, aud, nonce, ttl) => {
    const k = `${act}:${aud}:${nonce}`;
    if (nonces.has(k)) return false;
    nonces.set(k, Date.now()); return true;
  },
};

const guard = aapGuard({ audience: 'my_api', getAgent, nonceStore });

app.post('/api/workorders', guard, (req, res) => {
  const { act, assertion } = req.aap;
  res.json({ ok: true, agent: act, intent: assertion.int });
});

On deny, the guard returns 403 with X-AAP-Reason. Add onEvent for audit logging.

Part 2: aap-agentkit (Agent / client)

Generate keypairs, register with your registry, and sign outgoing requests.

1. Install

npm install aap-agentkit

2. Generate keypair and register

const { generateKeyPair, register } = require('aap-agentkit');

const kp = generateKeyPair();
const reg = await register({
  registryUrl: 'https://registry.example.com',
  agentName: 'My Agent',
  publicKeyBase64: kp.publicKeyBase64,
  requestedAudiences: ['my_api'],
  requestedIntents: ['workorders.create'],
});

const { agentId, allowedIntents } = reg;
// If your registry uses principal-actor, grant delegations per intent

3. Sign and send API requests

const { createSignedHeaders } = require('aap-agentkit');

const body = { title: 'Fix leak' };
const bodyStr = JSON.stringify(body);
const { headers } = createSignedHeaders({
  url: 'https://api.example.com/workorders',
  method: 'POST',
  body: bodyStr,
  intent: 'workorders.create',
  audience: 'my_api',
  agentId,
  privateKey: kp.privateKey,
  subject: 'usr_123',  // on-behalf-of user
});

await fetch('https://api.example.com/workorders', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: bodyStr,
});

Discovery

Expose GET /.well-known/aap with registryUrl, audience, intents.

ClawHub / OpenClaw Skill

Ship AAP as a skill: config (registry URL, audience), key storage, aap.register() and aap.call({ intent, path, body }).

Try Playground →