@agentronics/sdk

Authentication for AI agents — verify every agent on your site (signed agents, API agents, crawlers, WebMCP and browser agents) with any method: Web Bot Auth, API keys, OAuth2, SSO, SPIFFE, mTLS.

Version: 0.5.0

Why Agentronics

AI agents already visit your site: crawlers indexing it for answer engines, assistants fetching pages on a user's behalf, browser agents clicking through checkout, and API agents calling your endpoints. Most sites can't tell a real ChatGPT agent from a scraper wearing its user agent — every agent looks the same.

Agentronics gives every agent a verifiable identity, the way an auth provider does for your human users: sign agents in and see who they are. Agentronics never blocks — agents that don't authenticate keep browsing your site as normal.

What you get

• Every kind of agent. Signed agents, API agents, search and AI crawlers, WebMCP and in-browser agents — one SDK, one identity model, one console.
• Every method. Web Bot Auth (signed HTTP requests), agent API keys, OAuth2, verified crawlers, SSO / OIDC, SPIFFE, mTLS and browser-agent credentials.
• Identity in your app. Verified agents reach your routes with their identity attached as request headers — who they are and how they proved it.
• Auth logs & sessions. Every sign-in and verification, with the method and the reason it passed or failed, in the Agentronics console.

Two halves, one identity

| | Runs | Authenticates | |---|---|---| | Server — @agentronics/sdk/server | Middleware on your server or edge (Next.js, Express, any Fetch runtime) | Anything that sends an HTTP request: signed agents, API agents, crawlers — including agents that never run your JavaScript | | Browser — @agentronics/sdk | In the page | WebMCP agents and browser agents operating your UI |

Most sites start with the server middleware — it sees 100% of agent traffic — and add the browser SDK when agents interact with the page itself.

Next

• Quickstart — verify your first agent in five minutes.
• How it works — the request flow, trust levels and results.
• Authentication methods — choose methods for your agents.

Quickstart

This guide adds agent authentication to a Next.js app. You'll verify signed agents and crawlers out of the box, then add API keys for your own agents. Using Express or another runtime? The steps are the same — see Express or any Fetch runtime.

1. Install

npm install @agentronics/sdk

2. Add the middleware

// middleware.ts
import { agentronicsMiddleware } from '@agentronics/sdk/next'

export default agentronicsMiddleware()

export const config = {
  // every page and API route; skip static assets
  matcher: ['/((?!_next|.*\\..*).*)'],
  // Node.js runtime so crawler claims can be checked by reverse DNS
  // (on the default edge runtime they stay unverified — never wrongly verified)
  runtime: 'nodejs',
}

That's a working setup. With no options it:

• verifies signed agents with Web Bot Auth — e.g. OpenAI's ChatGPT agent,
• verifies search and AI crawlers by reverse DNS, so a scraper claiming to be Googlebot doesn't pass,
• lets every request through — Agentronics never blocks.

3. Read the verified agent in your routes

The middleware forwards the result as request headers. Read them with readAgentHeaders:

// app/api/products/route.ts
import { headers } from 'next/headers'
import { readAgentHeaders } from '@agentronics/sdk/server'

export async function GET() {
  const agent = readAgentHeaders(await headers())

  if (agent.status === 'verified') {
    console.log(`${agent.name} (${agent.method}) is reading products`)
  }
  return Response.json({ products: [] })
}

The middleware strips any x-agentronics-* header the caller sent, so these values can't be forged — as long as the route sits behind the middleware.

4. Give your own agents API keys

For agents you or your customers run, issue agent API keys:

import { agentronicsMiddleware } from '@agentronics/sdk/next'
import { staticKeyVerifier } from '@agentronics/sdk/server'

export default agentronicsMiddleware({
  apiKey: {
    // sha256(key) → identity; mint keys with generateAgentKey()
    verify: staticKeyVerifier(JSON.parse(process.env.AGENT_KEYS ?? '{}')),
  },
})

Agents send Authorization: Bearer agk_…. See Agent API keys.

5. See it in the console

Stream results to the Agentronics console to get auth logs, sessions and your monthly active agents — see Stream auth events to the console.

Next

• Authentication methods — OAuth2, SSO, SPIFFE, mTLS and more.
• Browser agents — authenticate WebMCP and in-page agents too.
• Server API reference — every option and result field.

Links

• Documentation
• Dashboard
• Changelog

License

MIT — © Agentronics.