Node.js SDK

Choose the package for your role

The Agent package calls AEP Services. The Service package exposes AEP operations and authenticates Agents. The Platform package is only for applications that host Agent identities and signing keys; an Agent can instead manage its own identity. Framework adapters bind the Service package to a web framework.

Install only what your application needs

The packages require Node.js 22 or newer and include TypeScript declarations. They are ESM-first with CommonJS entry points. Install the role package and, for a Service using a web framework, its matching adapter. npm resolves declared dependencies; use pnpm or Yarn if that is what your application uses.

# Agent application
npm install @aep-foundation/agent
# Service application
npm install @aep-foundation/service
# Express Service adapter
npm install @aep-foundation/service @aep-foundation/express express

Start an Agent integration

An Agent starts from the Service URL, reads Inspect, enrolls a Service-scoped identity, and checks the resulting status. This example uses the optional Platform identity provider to obtain assertions. Replace the illustrative Platform URL and token with your own configuration; a self-managed identity provider is another supported choice. Only submit claims the Service requests and your Agent can provide.

import { createAepAgent, createPlatformIdentityProvider } from "@aep-foundation/agent";

const agent = createAepAgent({
  identityProvider: createPlatformIdentityProvider({
    authorization: "Bearer <platform-token>",
    platformUrl: "https://platform.example.com"
  })
});
const session = agent.serviceSession({ serviceUrl: "https://api.example.com" });

const inspect = await session.inspect();
await session.enroll({ claims: { "contact.email": "ops@example.com" } });
const status = await session.status();

The returned inspect describes commands, identity methods, claims, and protected-resource authentication methods. The status result may still be pending; Enroll is not a promise of immediate resource access. Follow Enroll an Agent for the full workflow, or run the repository's Enroll and Status example with its paired Service and Platform examples.

Build a Service on the core, then choose an adapter

createAepService() accepts the Service DID, advertised capabilities, assertion verification, enrollment policy, and stores. The Express, Fastify, Hono, and Next.js adapters mount its HTTP handlers; protected application routes still need the Service's authentication decision and application authorization. Start with the Express example or the matching framework adapter. The Publish an Inspect document page explains the Service advertisement before routing.

Use a hosted identity only when it fits

A hosted identity Platform provisions a Service-scoped Agent DID and signs assertions without exporting its private key. The Agent still sends AEP commands directly to the Service, which verifies the signed assertion. The Platform-hosted identity guide explains the roles. The ephemeral Platform example is for local development, not production key custody.

When Platform signing returns pending, the Agent SDK exposes that result. An application can supply pendingSignResolver to wait for its Platform's continuation process; without one, the SDK raises AepPendingSignError. Do not treat a pending response as a signed assertion or assume every Platform exposes the same completion workflow. See the Agent package documentation for the resolver contract and cancellation behavior.