Agent identity federation

​

What federation does

• A user has agents in multiple SaaS apps that need to talk to each other
• An agent orchestrator delegates sub-tasks to agents registered at different services
• You run a multi-service architecture and want unified agent identity

​

How it works

1. Service A issues a federation token for one of its agents
2. The agent presents that token to Service B
3. Service B fetches Service A’s public key from /.well-known/kavach-federation.json
4. Service B verifies the token signature, checks expiry, and applies trust level rules
5. Service B now has a FederatedAgent object with the agent’s identity and (possibly downgraded) permissions

​

Setup

​

Trust levels

​

Issuing federation tokens

const result = await federation.issueFederationToken({
  agentId: "agent-123",
  permissions: ["read:data", "write:reports"],
  trustScore: 0.85,
  delegationScope: ["tool:github"],
  targetInstance: "service-b", // optional audience restriction
});

if (result.success) {
  // Give result.data.token to the agent
  console.log(result.data.token);
  console.log(result.data.expiresAt);
}

• sub: agent ID
• iss: source instance ID
• aud: target instance ID (if specified)
• exp: expiration time
• permissions: agent permissions array
• trust_score: source instance’s trust assessment (0-1)
• delegation_scope: what the agent is allowed to delegate
• credential: optional embedded Verifiable Credential JWT

​

Verifying federation tokens

const result = await federation.verifyFederationToken(token);

if (result.success) {
  const agent = result.data;
  console.log(agent.agentId);          // "agent-123"
  console.log(agent.sourceInstance);    // "service-a"
  console.log(agent.permissions);      // ["read:data", "write:reports"]
  console.log(agent.trustScore);       // 0.85
  console.log(agent.delegationScope);  // ["tool:github"]
}

1. Token signature matches the source instance’s public key
2. Token has not expired
3. Source instance is in the trusted list (or autoTrust is on)
4. Audience matches this instance (if audience is set in the token)
5. Trust level rules are applied to downgrade permissions if needed

​

Embedding Verifiable Credentials

import { createVCIssuer } from "kavachos/vc";

// Issue a VC for the agent
const vcResult = await vcIssuer.issueAgentCredential({
  agentId: "agent-123",
  permissions: ["read:data"],
  trustLevel: 0.85,
});

// Embed it in the federation token
const fedResult = await federation.issueFederationToken({
  agentId: "agent-123",
  permissions: ["read:data"],
  trustScore: 0.85,
  credential: vcResult.data.jwt,
});

​

Discovery protocol

GET /.well-known/kavach-federation.json

{
  "instanceId": "service-a",
  "instanceUrl": "https://a.example.com",
  "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." },
  "protocolVersion": "1.0",
  "features": ["federation-tokens", "vc-embedding", "auto-discovery"]
}

const result = await federation.discoverInstance("https://a.example.com");

​

Security considerations

• Short TTLs: Default is 5 minutes. Keep tokens short-lived to limit blast radius.
• Audience restriction: Use targetInstance to prevent token replay at unintended services.
• Key rotation: Rotate signing keys periodically. When you rotate, update the well-known endpoint and notify trusted instances.
• Discovery vs. pre-configuration: Discovery is convenient for dev, but pre-configure public keys in production for stronger security guarantees.
• Auto-trust is for development only: In production, always explicitly configure trusted instances.
• Trust levels are enforced by the verifier: The source instance cannot override the target’s trust level setting. A limited trust target will always strip write permissions regardless of what the source claims.

​

Full example

import { createFederationModule } from "kavachos/auth";
import { generateKeyPair, exportJWK } from "jose";

const { publicKey, privateKey } = await generateKeyPair("EdDSA");

const federation = createFederationModule({
  instanceId: "service-a",
  instanceUrl: "https://a.example.com",
  signingKey: privateKey,
});

// Expose well-known endpoint
app.get("/.well-known/kavach-federation.json", async (req, res) => {
  const identity = await federation.getInstanceIdentity();
  res.json(identity);
});

// When an agent needs to talk to Service B
app.post("/agents/:id/federate", async (req, res) => {
  const result = await federation.issueFederationToken({
    agentId: req.params.id,
    permissions: agent.permissions,
    trustScore: agent.trustScore,
    targetInstance: "service-b",
  });

  if (!result.success) {
    return res.status(500).json(result.error);
  }

  res.json({ federationToken: result.data.token });
});

import { createFederationModule } from "kavachos/auth";
import { generateKeyPair } from "jose";

const { privateKey } = await generateKeyPair("EdDSA");

const federation = createFederationModule({
  instanceId: "service-b",
  instanceUrl: "https://b.example.com",
  signingKey: privateKey,
  trustedInstances: [
    {
      instanceId: "service-a",
      instanceUrl: "https://a.example.com",
      publicKey: serviceAPublicJwk,
      trustLevel: "full",
    },
  ],
});

// Verify federation tokens on incoming requests
app.use("/agents/federated/*", async (req, res, next) => {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });

  const result = await federation.verifyFederationToken(token);
  if (!result.success) {
    return res.status(403).json(result.error);
  }

  req.federatedAgent = result.data;
  next();
});