Examples
Proof-first runtime and backend patterns for common agent scenarios
/
Runtime Request: Send X-Lemma-Credential
This is the default request pattern for new agent integrations. Load the signed proof from disk or memory and attach it directly to protected requests.
Node.js
import fs from 'node:fs/promises';
const proof = JSON.parse(await fs.readFile(process.env.LEMMA_PROOF_FILE, 'utf8'));
const encodedProof = Buffer.from(JSON.stringify(proof)).toString('base64url');
const response = await fetch('https://api.example.com/api/agent/run', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Lemma-Credential': encodedProof,
},
body: JSON.stringify({ action: 'site.read' }),
});
if (!response.ok) {
const error = await response.json();
console.error('Lemma-protected request failed:', error);
}
Protected Backend Route
On your server, decode the header, verify the signed proof, and derive the principal only after verification succeeds.
Express
app.post('/api/agent/run', async (req, res) => {
const encoded = (req.header('X-Lemma-Credential') || '').trim();
if (!encoded) {
return res.status(401).json({
success: false,
error: 'auth_required',
message: 'Provide X-Lemma-Credential',
});
}
const credential = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
const verification = await verifyCredentialWithTrust(credential);
if (!verification.valid) {
return res.status(401).json({
success: false,
error: `invalid_lemma:${verification.reason || 'verification_failed'}`,
message: 'Credential verification failed',
});
}
const claims = credential.claims || credential.credentialSubject || {};
const subject = credential.subject || claims.ppid || claims.id;
return res.json({
success: true,
actor: subject,
auth_method: 'lemma_header',
});
});
Verification Checklist
- Verify issuer trust and signature
- Check expiry / freshness
- Check audience or site binding
- Check required scope or permission
- Deny by default on ambiguous or missing context
Compatibility Mode: Exchange Proof for Bearer
Use this only when an existing integration cannot yet send X-Lemma-Credential directly.
cURL
curl -s -X POST "https://lemma.id/api/auth/exchange-proof" \
-H "Content-Type: application/json" \
-d '{
"credential": { "...": "signed lemma object" },
"site_id": "example.com",
"requested_scope": ["read"],
"ttl_seconds": 900
}'
Decision Monitoring
Use the monitoring APIs to inspect runtime activity from your own UI or internal dashboards.
cURL
curl -s "https://lemma.id/api/agent/monitor/summary?hours=24" \
-H "X-API-Key: lemma_xxx"
Reference Runtime Path
If you want a complete reference implementation with gateway, conformance checks, and kill-switch validation, use the optional Lemma Firewall onboarding path.
Shell
lemma setup-openclaw --api-base https://lemma.id