Enable Security for AI Agents

Give your AI agents verified identities, scoped capabilities, and auditable authorization. This guide walks through registering an agent, issuing signed credentials, authorizing calls with the Ask API, and optionally requesting just-in-time permissions for sensitive actions.

Prerequisites

• A LumoAuth organization with AAuth enabled — sign up at app.lumoauth.dev
• Node.js 18+ or Python 3.9+

---

Step 1: Register Your Agent

Every agent needs a registered identity. In the Organization Portal, go to AI Agents → Register Agent.

Field	Value
Name	Your agent name (e.g. summarizer-agent)
Capabilities	The permissions this agent may request
JWKS URL	Your agent's public key endpoint (or paste a JWKS)

Or register via API:

curl -X POST https://app.lumoauth.dev/orgs/YOUR_ORG_ID/api/v1/agents/register \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-agent",
    "capabilities": ["document.read", "document.summarize"],
    "jwks": { "keys": [{ ... }] }
  }'

---

Step 2: Generate Agent Credentials

Agents authenticate with signed JWTs backed by a key pair (Ed25519 recommended).

Generate a key pair

// Node.js
const crypto = require('crypto');

const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
});
console.log('Public key:\n', publicKey);
console.log('Private key (store securely):\n', privateKey);

# Python
from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.hazmat.primitives import serialization

private_key = ed25519.Ed25519PrivateKey.generate()
public_key = private_key.public_key()

pub_pem = public_key.public_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PublicFormat.SubjectPublicKeyInfo,
)
print(pub_pem.decode())

Provide the public key when registering the agent. Keep the private key in your secret manager.

---

Step 3: Authenticate Your Agent (Get a Token)

The agent signs a short-lived JWT assertion and exchanges it for an access token:

// Node.js — using @lumoauth/agents SDK
const { AgentAuth } = require('@lumoauth/agents');

const agent = new AgentAuth({
  orgId: 'YOUR_ORG_ID',
  agentId: 'YOUR_AGENT_ID',
  privateKeyPem: process.env.AGENT_PRIVATE_KEY,
});

const token = await agent.getAccessToken({
  capabilities: ['document.read', 'document.summarize'],
});

# Python — using lumoauth-agents SDK
from lumoauth.agents import AgentAuth
import os

agent = AgentAuth(
    org_id="YOUR_ORG_ID",
    agent_id="YOUR_AGENT_ID",
    private_key_pem=os.environ["AGENT_PRIVATE_KEY"],
)

token = await agent.get_access_token(
    capabilities=["document.read", "document.summarize"]
)

---

Step 4: Authorize Agent Actions

Use the Ask API for natural-language permission checks — ideal inside LLM reasoning loops:

curl -X POST https://app.lumoauth.dev/orgs/YOUR_ORG_ID/api/v1/agents/ask \
  -H "Authorization: Bearer AGENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "Can I read and summarize documents for user alice@acme.com?"}'

{
  "allowed": true,
  "reason": "Agent has document.read and document.summarize capabilities scoped to organization."
}

Or use a traditional permission check:

curl -X POST https://app.lumoauth.dev/orgs/YOUR_ORG_ID/api/v1/authz/check \
  -H "Authorization: Bearer AGENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permission": "document.summarize", "subject": "agent:summarizer-agent"}'

---

Step 5: Request JIT Permissions (Optional)

For sensitive operations, request just-in-time approval rather than holding standing permissions:

const approval = await agent.requestJitPermission({
  permission: 'payments.authorize',
  justification: 'Processing end-of-month vendor invoices',
  expiresIn: '10m',
});

if (approval.granted) {
  await processPayments(approval.token);
}

LumoAuth notifies a human approver and returns the decision in real time. The granted token is scoped to that single operation and expires automatically.

---

Step 6: Framework Integrations

Jump straight to a framework-specific guide:

Framework	Guide
LangChain / LangGraph	Registry · JIT
CrewAI	Registry · JIT
OpenAI Agents SDK	Registry · JIT
Agno	Registry · JIT
Google ADK	Registry · JIT

---

What's Next

Topic	Description
AI Access Control	Full AI access control documentation for AI agents
AAuth Protocol	Detailed AAuth protocol spec
Ask API	Natural language authorization for LLMs
JIT Permissions	Human-in-the-loop approval flows
Chain of Agency	Token exchange for agent delegation
Workload Federation	Federate with cloud workload identities
MCP Servers	Secure Model Context Protocol servers