TypeScript SDK

Verify AgentID identity and signed factual records in your application's server.

Install the ESM server package from opencatalog’s hosted release:

npm install https://opencatalog.sh/sdk/opencatalog-records-0.1.0.tgz

The package name is @opencatalog/records. This tarball is hosted by opencatalog; it is not published to the npm registry. Use Node.js 20 or later. Keep application keys and private grants on your server.

Check a signed record

Create the client once in your server module and reuse it:

import { createOpencatalogClient } from '@opencatalog/records';

const opencatalog = createOpencatalogClient();

export async function checkAgent(reference: string, idToken: string, nonce: string) {
  const checked = await opencatalog.check({
    reference,
    idToken,
    agentIdAudience: process.env.AGENTID_CLIENT_ID!,
    nonce,
    requiredChecks: ['inbox'],
  });
  return checked.record;
}

Use your receiving application’s AgentID audience and stored OAuth nonce. The client verifies the current AgentID identity and the record’s signature, exact facts, issuer/subject binding, and expiry. Required checks must be passed and current. Choose requiredChecks from identity, inbox, retry_wait, task, and distraction; omit it when you only need the factual record.

Success returns status checked, the verified identity, record, expiresAt, and refreshAt. It does not return authorization. Your application decides whether those facts are sufficient for the requested action. The SDK does not assign an overall trust score or authorize spending, data access, or tool use.

The lower-level verifyAgentIdentity and createRecordClient().lookup remain available when your application needs separate authentication and record lookup steps. A copied badge or an unrelated verified identity is insufficient.

Private records and freshness

const privateRecords = createOpencatalogClient({
  appKey: process.env.OPENCATALOG_API_KEY!,
  grant: process.env.OPENCATALOG_GRANT!,
  audience: recipientAppId,
});
const verified = await privateRecords.check({
  reference: recordReference,
  idToken,
  agentIdAudience: process.env.AGENTID_CLIENT_ID!,
  nonce: expectedNonce,
  requiredChecks: ['inbox'],
  freshnessMs: 0,
});

Private reads require the matching application key, approved grant, and recipient audience. Do not share the client’s private cache between recipients. Owner permission withdrawal blocks new reads; a previously verified snapshot can remain usable only until its signed expiry, at most five minutes. Set freshnessMs to zero for an action requiring a fresh authorized read.

Reuse a client to use its verified cache. A warm lookup uses no network requests until the snapshot’s refresh limit; check evidence expiration can shorten that limit. A cold lookup may fetch both the record and opencatalog’s signing keys. AgentID authentication key requests are separate. No model prompt or agent tool call is required.

An unavailable, expired, mismatched, or invalid record raises RecordUnavailableError with outcome unknown and a typed code such as missing_checks, identity_mismatch, inactive_record, or expired. Handle that explicitly with review, reduced permissions, or another verification step. Do not convert an error into a passed check.

Record format and privacy documents the HTTP contract. HTTP access remains available for integrations in other languages.