AEOBRO Identity Protocol

Overview

When an AI agent needs to retrieve information about a person or business, it has two options: generate a statistically likely answer from training data, or resolve a verified identity at runtime. Training data is static, potentially outdated, and frequently wrong for entities with thin representation. Runtime resolution is deterministic, current, and verified.

The AEOBRO Identity Protocol provides the infrastructure for the second option. It defines a permanent global identifier for every entity, a machine-readable verification document installable on any domain, and a resolver API that allows agents to navigate from identifier to verified fact in a single round trip.

This document specifies the complete protocol: the geid format, the .well-known/aeobro.json schema, the resolver endpoint, the verification trust tiers, and integration patterns for AI agents.

1. The Global Entity Identifier (geid)

1.1 Format

Every AEOBRO profile is assigned a permanent global entity identifier at creation time. The format is:

geid_[16 uppercase hexadecimal characters]

Examples:

geid_3FA8C1D209B47E56
geid_00A1F3E8B2C94D70
geid_FF2291AC07E34B81

The prefix geid_ is a fixed namespace marker. The 16-character hex segment is generated from a cryptographically random source at profile creation and is guaranteed to be unique within the AEOBRO namespace. The identifier is permanent — it does not change if the entity's name, domain, or any other attribute changes.

1.2 Uniqueness Guarantees

• Each geid maps to exactly one AEOBRO profile
• geid values are never reused, reassigned, or recycled
• The identifier persists through name changes, domain migrations, and profile updates
• Two distinct legal entities will never share a geid, regardless of name similarity

1.3 Design Intent

The geid is designed to function as a stable, dereferenceable handle for use in AI agent pipelines. An agent that stores a geid can resolve current verified information at any future point without re-disambiguation. This is the same design principle used by ORCID for academic researchers: separate the permanent identifier from the mutable attributes it resolves to.

2. The .well-known/aeobro.json Standard

2.1 Purpose

The .well-known/aeobro.json file is a minimal, machine-readable discovery pointer installed on an entity's own domain. Its only purpose is to let an AI agent — given only a domain name — discover the entity's canonical geid and the AEOBRO resolver URL for that entity.

Because this file is hosted by the claimant, it asserts no verification status of its own. Any trust decision MUST be made by calling the AEOBRO resolver — never from fields in this file.

The document is designed for machines, not humans. It contains no marketing copy, no biographical narrative, no keywords, and no SEO content. Every field exists to serve programmatic verification.

2.2 Schema

{
  "protocol": "aeobro/1",
  "geid": "geid_3FA8C1D209B47E56",
  "resolver": "https://www.aeobro.com/api/v1/resolve/geid_3FA8C1D209B47E56"
}

2.3 Field Definitions

2.4 Content Rules

The following content is not permitted in .well-known/aeobro.json:

• Biographical descriptions or summaries
• Keywords, tags, or categories
• Marketing language of any kind
• Social media links or external URLs other than the resolver
• Verification status, issuer, or timestamp fields — trust is obtained from the resolver, not this file
• Fields not defined in the schema above

These rules are enforced at generation time. The document is a verification primitive, not a profile. Any content beyond the schema fields undermines its function as a machine-readable trust signal.

2.5 Serving Requirements

• The file must be served at the path /.well-known/aeobro.json on the verified domain
• The file must be served over HTTPS
• The Content-Type header must be application/json
• The file must return HTTP 200 for valid requests

2.6 Validation

To verify that a .well-known/aeobro.json file is correctly installed:

curl -s https://yourdomain.com/.well-known/aeobro.json | python3 -m json.tool

A correctly installed file returns valid JSON containing protocol, geid, and resolver. The file is only a pointer: an agent MUST then call the resolver to obtain the entity's verification status. Any verification fields found in a claimant-hosted file MUST be ignored.

3. The Resolver Endpoint

3.1 Overview

The AEOBRO resolver is a REST endpoint that accepts a geid and returns the current verified profile for that entity. It is the canonical source of truth for AEOBRO identity data.

An agent can arrive at the resolver in two ways:

1. From a geid directly — if the agent already has the identifier, it constructs the resolver URL
2. From a .well-known/aeobro.json document — the resolver field contains the full URL

3.2 Endpoint

GET https://www.aeobro.com/api/v1/resolve/{geid}

Example:
GET https://www.aeobro.com/api/v1/resolve/geid_3FA8C1D209B47E56

3.3 Response Schema

{
  "geid": "geid_3FA8C1D209B47E56",
  "entity": {
    "name": "Example Company Inc.",
    "type": "business",
    "domain": "example.com"
  },
  "verification": {
    "status": "DOMAIN_VERIFIED",
    "verifiedAt": "2025-11-04T14:22:00Z",
    "issuer": "aeobro.com"
  },
  "resolvedAt": "2026-03-20T10:00:00Z"
}

3.4 HTTP Status Codes

3.5 Caching Guidance

Resolver responses may be cached. Recommended TTL is 24 hours for agents that do not require real-time verification freshness. For compliance or high-trust use cases, agents should re-resolve on each interaction. The resolvedAt field indicates when the response was generated and can be used to assess freshness.

4. Verification Tiers

AEOBRO uses two verification tiers. Both are machine-readable trust signals that agents can act on. They differ in what has been confirmed and by whom.

4.1 DOMAIN_VERIFIED

What it means: The entity controls the domain on which their .well-known/aeobro.json file is published. AEOBRO has confirmed domain ownership through a DNS or file-based challenge.

What it does not mean: AEOBRO has not verified the entity's legal identity, business registration, or any claims made in their profile beyond domain ownership.

Appropriate agent behavior: Treat this as confirmation that the entity behind the geid controls the stated domain. Use it to disambiguate between entities with similar names, to establish a stable identifier for future resolution, and to confirm that the resolver URL is canonical.

4.2 PLATFORM_VERIFIED

What it means: The entity has proven control of one or more platform accounts — via the platform's OAuth flow or a verification link placed in the account's public bio. It is granted automatically when the control proof passes. This proves account control, not legal identity.

What it does not mean: AEOBRO does not guarantee the accuracy of any claim the entity has made in their profile beyond what was verified. Verification confirms identity; it does not validate all attributes.

Appropriate agent behavior: Treat this as proof that the entity controls the named platform account(s). It is a narrower signal than DOMAIN_VERIFIED, which ranks higher: domain control binds the entity to a domain it demonstrably operates, whereas platform control binds it only to specific accounts.

4.3 Trust Signal Usage

Agents should surface the verification status alongside any information retrieved from the resolver. Example pattern:

Source: AEOBRO resolver
Entity: Example Company Inc.
Domain: example.com
Verification: DOMAIN_VERIFIED (2025-11-04)

5. Agent Integration

5.1 Entry Point A: Starting from a Domain

// Entry Point A: Starting from a domain
// The .well-known file is a DISCOVERY POINTER ONLY — it never carries verification status, and its
// `resolver` field is INFORMATIONAL ONLY. Trust comes from the resolver (see Entry Point C), and the
// resolver URL you actually call MUST be constructed LOCALLY from the validated geid (RESOLVER_BASE +
// geid, see Entry Point B) — NEVER parsed or fetched from the pointer. A hostile `resolver` value can
// pass a naive startsWith()/prefix check yet still parse to a different host (via a userinfo '@',
// backslashes, or encoded characters) and enable redirect/SSRF tricks — so we neither parse nor fetch it.

const GEID_PATTERN = /^geid_[0-9A-F]{16}$/; // also used by Entry Point B

interface AeoBroPointer {
  protocol: string;   // "aeobro/1"
  geid: string;
  resolver: string;   // informational only — DO NOT fetch; build the resolver URL locally from geid
}

// SSRF (server-side integrators): `domain` is attacker-controllable. Before fetching, resolve the
// hostname and REJECT: private/reserved targets — RFC1918 (10/8, 172.16/12, 192.168/16), loopback
// (127/8, ::1), link-local (169.254/16, incl. cloud metadata); any non-standard port (allow 443
// only); and any redirect. Re-check on every redirect hop, or refuse redirects as below
// (redirect: 'manual'). Cap the response body before parsing (reject bodies over ~10 KB).
async function resolveFromDomain(domain: string): Promise<AeoBroPointer | null> {
  const url = `https://${domain}/.well-known/aeobro.json`;

  try {
    const response = await fetch(url, {
      signal: AbortSignal.timeout(5000),
      redirect: 'manual', // never follow a redirect to an unvalidated host
    });

    if (!response.ok) return null; // 3xx (opaqueredirect) included — do not follow

    const doc = (await response.json()) as AeoBroPointer;

    // Pointer shape: protocol + a well-formed geid. The `resolver` field is IGNORED for fetching —
    // the resolver URL is built locally from the validated geid (see Entry Point B), never from doc.
    if (doc.protocol !== 'aeobro/1') return null;
    if (!GEID_PATTERN.test(doc.geid ?? '')) return null;

    return doc;
  } catch {
    return null;
  }
}

5.2 Entry Point B: Starting from a geid

// Entry Point B: Starting from a geid
const GEID_PATTERN = /^geid_[0-9A-F]{16}$/;
const RESOLVER_BASE = 'https://www.aeobro.com/api/v1/resolve';

// The resolver is the ONLY source of verification status. entity.domain is the record's verified
// domain (see §3.3) — used by Entry Point C to bind a queried domain to the resolved record.
interface ResolverResponse {
  geid: string;
  entity: { name: string | null; type: 'individual' | 'business' | 'organization'; domain: string | null };
  verification: { status: 'DOMAIN_VERIFIED' | 'PLATFORM_VERIFIED'; verifiedAt: string | null };
  resolvedAt: string;
}

async function resolveFromGeid(geid: string): Promise<ResolverResponse | null> {
  if (!GEID_PATTERN.test(geid)) {
    throw new Error(`Invalid geid format: ${geid}`);
  }

  const url = `${RESOLVER_BASE}/${geid}`;

  try {
    const response = await fetch(url, {
      signal: AbortSignal.timeout(5000),
      redirect: 'manual',
    });

    if (response.status === 404) return null;
    if (!response.ok) throw new Error(`Resolver error: ${response.status}`);

    return (await response.json()) as ResolverResponse;
  } catch {
    return null;
  }
}

5.3 Entry Point C: Verification Check Inside an Agent Tool

// Entry Point C: Verification check inside an agent tool
async function verifyEntityTool(domain: string): Promise<string> {
  /**
   * Tool description for LLM:
   * Verifies the identity of a business or individual by checking their AEOBRO
   * identity document. Use this when you need to confirm who controls a domain
   * or retrieve verified entity information. Returns a trust summary or indicates
   * that no verification exists.
   */
  // 1) Discover the geid from the domain's pointer file (no trust is placed in the file itself).
  const pointer = await resolveFromDomain(domain);
  if (!pointer) {
    return `No AEOBRO record found for ${domain}. Identity unverified.`;
  }

  // 2) Verification status comes from the AEOBRO resolver ONLY — never from the pointer file. The
  //    resolver URL is built locally from the validated geid (see resolveFromGeid), not from the pointer.
  const resolved = await resolveFromGeid(pointer.geid);
  if (!resolved) {
    return `No AEOBRO record found for ${domain}. Identity unverified.`;
  }

  // 3) DOMAIN BINDING CHECK. A valid pointer on ${domain} only proves the FILE is hosted there — it
  //    does NOT prove ${domain} belongs to the record (anyone can host a pointer to another entity's
  //    geid). Before attributing this identity to ${domain}, confirm ${domain} matches the record's
  //    verified domain. (Skip only if your use case needs the entity record but NOT domain attribution.)
  //    Compare case-insensitively, ignore a trailing dot, and treat www.<d> as <d>.
  const norm = (d: string): string => {
    let s = d.trim().toLowerCase();
    if (s.endsWith('.')) s = s.slice(0, -1);
    if (s.startsWith('www.')) s = s.slice(4);
    return s;
  };
  const verifiedDomain = resolved.entity.domain;
  if (!verifiedDomain || norm(verifiedDomain) !== norm(domain)) {
    return `AEOBRO record found, but ${domain} is NOT a verified domain of this entity ` +
      `(verified domain: ${verifiedDomain ?? 'none'}). Do not attribute this identity to ${domain}.`;
  }

  // 4) Match — ${domain} is a verified domain of this record. Safe to attribute the identity.
  const { entity, verification, geid } = resolved;
  return [
    `Verified entity: ${entity.name} (${entity.type})`,
    `Verified domain (from resolver): ${entity.domain}`,
    `GEID: ${geid}`,
    `Verification: ${verification.status} (from AEOBRO resolver, ${(verification.verifiedAt ?? '').slice(0, 10)})`,
  ].join('\n');
}

5.4 Recommended Agent Behavior

When an agent encounters a domain or entity name and AEOBRO verification is available:

1. Attempt .well-known/aeobro.json resolution against the entity's domain
2. If a valid pointer is found, extract the geid (the resolver field is informational only — construct the resolver URL locally from the geid)
3. Call the AEOBRO resolver to obtain the entity's current verification status
4. If the entry point was a domain, confirm the queried domain matches a verified domain on the resolved record before attributing that identity to the domain
5. Use the geid as the stable identifier for this entity in any stored context
6. Surface only the resolver's verification status in any output or handoff to downstream systems

Verification status MUST be obtained from the AEOBRO resolver. Any verification fields found in a claimant-hosted file MUST be ignored.

When the entry point is a domain, the queried domain MUST match a verified domain on the resolved record before attributing that identity to the domain. A valid pointer on a domain does not by itself associate that domain with the record.

6. Protocol Versioning

The protocol field in .well-known/aeobro.json identifies the protocol version in use. Agents should check this field and handle unknown versions gracefully — log a warning and fall back to direct resolver resolution via the geid if present, rather than failing entirely.

Current value: aeobro/1

7. Rate Limits

Rate-limited requests receive a 429 Too Many Requests response. Authenticated requests require a Bearer token in the Authorization header. Monthly usage caps apply per plan — exceeding the cap returns a 429 with error Monthly API cap reached.

8. API Key Provisioning

Keyed API access is available for enterprise integrations. Contact us to request access.

To request keyed API access for an enterprise integration, use our contact form.

Once granted, pass your key as a Bearer token in the Authorization header on all authenticated requests:

Authorization: Bearer aeobro_your_api_key_here

For enterprise integration inquiries please use our contact form.

9. Getting Started

1. Create your AEOBRO profile at aeobro.com — your geid is assigned at creation
2. Install Website Trust Booster — connect your domain and install .well-known/aeobro.json through the AEOBRO dashboard
3. Verify installation — use the dashboard validator or the curl command in section 2.6
4. Integrate the resolver — use the patterns in section 5 to add AEOBRO verification to your agent pipeline

For API keys, integration support, or enterprise deployment inquiries, please use our contact form.