Demo Service

A zero-dependency HTTP service that authenticates AI agents via Alien Agent ID tokens. Use it as a reference implementation or to test your agent’s authentication flow.

Starting the Service


node demo-service.mjs [--port 3141]

The service starts on port 3141 by default (configurable via --port or PORT environment variable).

Endpoints

Public

Method	Path	Description
`GET`	`/`	Landing page with documentation
`GET`	`/api/status`	Service status (uptime, known agent count)

Protected (Require `Authorization: AgentID <token>`)

Method	Path	Description
`GET`	`/api/whoami`	Agent identity info (fingerprint, owner, request count)
`GET`	`/api/protected`	Access secret data
`POST`	`/api/echo`	Echo request body
`GET`	`/api/agents`	List all known agents

Quick Test


# Generate a token and call the whoami endpoint
curl -H "$(node cli.mjs auth-header --raw)" http://localhost:3141/api/whoami

Response:


{
  "ok": true,
  "agent": {
    "fingerprint": "f5d9fac49457e9e...",
    "owner": "00000003010000000000539c741e0df8",
    "firstSeen": "2026-03-27T10:00:00.000Z",
    "requests": 1,
    "authenticatedAt": "2026-03-27T10:00:01.000Z"
  },
  "message": "Hello, agent f5d9fac49457e9e3! Your identity is verified."
}

Testing Error Cases


# No auth header
curl http://localhost:3141/api/whoami
# → 401: {"error": "Missing header: Authorization: AgentID <token>"}
 
# Invalid token
curl -H "Authorization: AgentID invalid" http://localhost:3141/api/whoami
# → 401: {"error": "Invalid token encoding"}
 
# Expired token (wait 5+ minutes after generating)
curl -H "Authorization: AgentID $OLD_TOKEN" http://localhost:3141/api/whoami
# → 401: {"error": "Token expired (age: 312s)"}

Using as a Reference

The demo service source (demo-service.mjs) demonstrates:

Parsing the Authorization: AgentID header
Calling verifyAgentToken() from lib.mjs
Tracking known agents in memory
Public vs. protected endpoint patterns
CORS handling for cross-origin requests

See the Service Integration Guide for detailed integration instructions with Express, Fastify, Flask, and Go examples.