Complete example of developer authentication, agent creation, and HTTP request signing

End-to-End Authentication Flow

This example demonstrates the complete flow from developer authentication to an agent making verified HTTP requests.

Overview

Developer                    Agent                       Service
    |                          |                            |
    |-- 1. beltic login ------>|                            |
    |                          |                            |
    |-- 2. Create agent ------>|                            |
    |                          |                            |
    |                          |-- 3. Sign request -------->|
    |                          |                            |
    |                          |<-- 4. Verified response ---|

Step 1: Developer Authentication

First, authenticate with the Beltic platform:

# Interactive login
beltic login

# Or non-interactive for CI/CD
beltic login --api-key $BELTIC_API_KEY --non-interactive

Verify your identity:

beltic whoami

Output:

Current Developer
----------------------------------------

  Developer ID: dev_m5x7k9p_a1b2c3d4e5f6
  Legal Name: Acme Corporation
  KYB Tier: tier_2 (Enhanced)
  Verified: Verified

Step 2: Create Agent with Keys

Generate a keypair for your agent:

beltic keygen --alg EdDSA --out agent-key.pem

Create the agent manifest and credential:

# Initialize agent manifest
beltic init --out agent-manifest.json

# Sign the agent credential
beltic sign \
  --payload agent-manifest.json \
  --key agent-key.pem \
  --out agent-credential.jwt

Step 3: Agent Signs HTTP Requests (TypeScript)

In your agent's TypeScript code:

import {
  signHttpRequest,
  importPrivateKey,
} from '@belticlabs/kya';
import fs from 'fs';

// Load the agent's private key
const pemContent = fs.readFileSync('agent-key.pem', 'utf-8');
const privateKey = await importPrivateKey(pemContent, 'EdDSA');

// Sign an HTTP request
const signedHeaders = await signHttpRequest({
  method: 'POST',
  url: 'https://api.example.com/payments/transfer',
  headers: {
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'USD',
    recipient: 'acct_123',
  }),
  privateKey,
  keyId: 'agent-key-thumbprint',
  keyDirectoryUrl: 'https://api.beltic.dev/v1/agents/agt_xxx/keys',
  credentialUrl: 'https://api.beltic.dev/v1/credentials/cred_xxx',
});

// Make the signed request
const response = await fetch('https://api.example.com/payments/transfer', {
  method: 'POST',
  headers: {
    ...signedHeaders,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'USD',
    recipient: 'acct_123',
  }),
});

Step 4: Service Verifies Request (TypeScript)

In your service's verification middleware:

import { verifyAgentRequest } from '@belticlabs/kya';
import type { Request, Response, NextFunction } from 'express';

async function verifyAgent(req: Request, res: Response, next: NextFunction) {
  const result = await verifyAgentRequest(req, {
    requiredScopes: ['payments:transfer'],
  });

  if (!result.verified) {
    return res.status(401).json({
      error: 'Unauthorized',
      code: result.error?.code,
      message: result.error?.message,
    });
  }

  // Attach verified agent info to request
  req.agent = result.agent;
  req.developer = result.developer;

  // Log for audit
  console.log(`Verified request from agent ${result.agent.id}`);
  console.log(`Developer: ${result.developer.legalName}`);
  console.log(`KYB Tier: ${result.developer.kybTier}`);

  next();
}

// Use in Express
app.post('/payments/transfer', verifyAgent, async (req, res) => {
  // req.agent and req.developer are now available
  const { amount, currency, recipient } = req.body;

  // Process the verified request...
  res.json({ success: true, transactionId: 'txn_xxx' });
});

Complete Working Example

Agent Code (agent.ts)

import { signHttpRequest, importPrivateKey } from '@belticlabs/kya';
import fs from 'fs';

async function makeVerifiedRequest() {
  // Load credentials
  const privateKey = await importPrivateKey(
    fs.readFileSync('agent-key.pem', 'utf-8'),
    'EdDSA'
  );

  const requestBody = JSON.stringify({
    action: 'transfer',
    amount: 100,
  });

  // Sign the request
  const headers = await signHttpRequest({
    method: 'POST',
    url: 'https://api.example.com/action',
    headers: { 'content-type': 'application/json' },
    body: requestBody,
    privateKey,
    keyId: process.env.AGENT_KEY_ID!,
    keyDirectoryUrl: process.env.KEY_DIRECTORY_URL!,
    credentialUrl: process.env.CREDENTIAL_URL!,
  });

  // Execute request
  const response = await fetch('https://api.example.com/action', {
    method: 'POST',
    headers: {
      ...headers,
      'content-type': 'application/json',
    },
    body: requestBody,
  });

  return response.json();
}

Service Code (server.ts)

import express from 'express';
import { verifyAgentRequest } from '@belticlabs/kya';

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

// Verification middleware
app.use('/api/*', async (req, res, next) => {
  const result = await verifyAgentRequest(req, {
    requiredScopes: ['api:access'],
  });

  if (!result.verified) {
    return res.status(401).json({ error: result.error?.message });
  }

  req.verifiedAgent = result;
  next();
});

// Protected endpoint
app.post('/api/action', (req, res) => {
  const { agent, developer } = req.verifiedAgent;

  res.json({
    success: true,
    processedBy: 'example-service',
    agent: agent.id,
    developer: developer.legalName,
  });
});

app.listen(3000);

Trust Chain Summary

When the service verifies the request, it confirms:

HTTP Signature Valid - Request hasn't been tampered with
Key Directory Valid - Agent's public key is registered
Agent Credential Valid - Agent is properly credentialed
Developer Credential Valid - Agent's developer is verified
Scopes Authorized - Agent has required permissions

This creates a complete trust chain from the service back to the verified developer.

End-to-End Authentication Flow

On this page