SDK & verify

Verification is the heart of the partner integration: your API sends the agent's session token to AgentOnboard's POST /api/verify, and AgentOnboard answers with the user's email — or a structured error. This page documents the exact contract and the official @agentonboard/sdk client that wraps it.

The one-line version

import { verify } from "@agentonboard/sdk";

const result = await verify(partnerKey, sessionToken);

if (result.ok) {
  const email = result.email; // the AgentOnboard login email
} else {
  const error = result.error; // a human-readable failure reason
}

Install

npm install @agentonboard/sdk

verify(partnerKey, sessionToken, apiUrl?)

The SDK exposes a single function:

verify(
  partnerKey: string,   // your partner key (Authorization: Bearer)
  sessionToken: string, // the agent's session token
  apiUrl?: string,      // defaults to "https://api.ao.aawej.in"
): Promise<VerifyResult>

apiUrl is optional and rarely needed — it exists for local development and self-hosting. The default points at the hosted AgentOnboard API.

VerifyResult

What the SDK sends

Under the hood, verify() makes exactly this request:

POST https://api.ao.aawej.in/api/verify
Authorization: Bearer <partnerKey>
Content-Type: application/json

{ "sessionToken": "<sessionToken>" }

The same call in plain fetch, if you prefer not to use the SDK:

const res = await fetch("https://api.ao.aawej.in/api/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${partnerKey}`,
  },
  body: JSON.stringify({ sessionToken }),
});

const body = await res.json();

The POST /api/verify contract

Request

Response

HTTP statuses

Reading the statuses

• 200 — success. The email in the response is the AgentOnboard login email of the user who minted the session token. This is the value you use to look up the account in your own system.
• 400 — the request itself was malformed: bad JSON, or a missing/non-string sessionToken. This is a client bug on the agent's side; your API should pass the token through untouched.
• 401 — authentication failed: the partner key or the session token is missing, invalid, or expired. Treat these as "unauthenticated" and return a 401 to the agent.
• 403 — the partner key is revoked. AgentOnboard maps its internal partner_key_revoked error to 403 so you can distinguish "this key is no longer valid" from "this token is no longer valid". Rotate the key in the partner dashboard and redeploy.
• 500 — an AgentOnboard server error. Retry with backoff; if it persists, contact support.

Error handling in practice

A robust handler distinguishes the failure classes so the agent gets a sensible response:

const result = await verify(partnerKey, sessionToken);

if (!result.ok) {
  // 400-class failures are the agent's fault — surface the message.
  if (result.error === "Invalid or expired session token") {
    return res.status(401).json({ error: "Session token invalid or expired" });
  }

  // The partner key itself is bad or revoked — this is on you, not the agent.
  if (result.error === "Partner key has been revoked") {
    console.error("Partner key revoked — rotate it in the dashboard");
    return res.status(500).json({ error: "Service misconfigured" });
  }

  return res.status(401).json({ error: "Authentication failed" });
}

Remember the SDK returns { ok: false, error: "Network error: cannot reach API" } when the API is unreachable — that is a server-side problem in your API, not an authentication failure.

Related

• Getting Started — wire this into your API in ten minutes
• Example app: REST API integration — how the notes app uses verify() with a TokenVerifyResult union
• Example app: create & read notes — the endpoints an agent actually calls

Next steps