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 identity verification document installed on an entity's own domain. Its purpose is to allow an AI agent — given only a domain name — to verify that the domain's owner has a confirmed AEOBRO identity, and to retrieve the canonical geid and resolver path for that entity.

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

{
  "version": "1.0",
  "geid": "geid_3FA8C1D209B47E56",
  "domain": "example.com",
  "resolver": "https://api.aeobro.com/v1/resolve/geid_3FA8C1D209B47E56",
  "entity": {
    "name": "Example Company Inc.",
    "type": "business"
  },
  "verification": {
    "status": "DOMAIN_VERIFIED",
    "verifiedAt": "2025-11-04T14:22:00Z",
    "issuer": "aeobro.com"
  },
  "generatedAt": "2025-11-04T14:22:00Z"
}

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
• 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
• The domain field in the file must match the domain from which it is served

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 will return valid JSON matching the schema above. An agent should additionally verify that the domain field matches the request domain before treating the document as valid.

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://api.aeobro.com/v1/resolve/{geid}

Example:
GET https://api.aeobro.com/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 completed AEOBRO's identity verification process, which includes document-based or credential-based confirmation of identity beyond domain ownership.

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 a higher-trust signal suitable for use cases where entity identity must be confirmed before proceeding. PLATFORM_VERIFIED entities have passed human-reviewed verification and represent a stronger trust anchor than domain ownership alone.

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
import fetch from 'node-fetch'; // or use native fetch in Node 18+

interface AeoBroDocument {
  version: string;
  geid: string;
  domain: string;
  resolver: string;
  entity: {
    name: string;
    type: 'individual' | 'business' | 'organization';
  };
  verification: {
    status: 'DOMAIN_VERIFIED' | 'PLATFORM_VERIFIED';
    verifiedAt: string;
    issuer: string;
  };
  generatedAt: string;
}

async function resolveFromDomain(domain: string): Promise<AeoBroDocument | null> {
  const url = `https://${domain}/.well-known/aeobro.json`;

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

    if (!response.ok) return null;

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

    // Validate domain field matches serving domain
    if (doc.domain !== domain) return null;

    // Validate required fields
    const required: (keyof AeoBroDocument)[] = [
      'version', 'geid', 'domain', 'resolver', 'entity', 'verification'
    ];
    if (!required.every((field) => field in doc)) 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://api.aeobro.com/v1/resolve';

async function resolveFromGeid(geid: string): Promise<AeoBroDocument | 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) });

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

    return (await response.json()) as AeoBroDocument;
  } 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.
   */
  const doc = await resolveFromDomain(domain);

  if (!doc) {
    return `No AEOBRO identity document found for ${domain}. Identity unverified.`;
  }

  const { entity, verification, geid } = doc;

  return [
    `Verified entity: ${entity.name} (${entity.type})`,
    `Domain: ${doc.domain}`,
    `GEID: ${geid}`,
    `Verification: ${verification.status} (issued by ${verification.issuer}, ${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 document is found, extract the geid and verification.status
3. Optionally call the resolver for the full current profile
4. Use the geid as the stable identifier for this entity in any stored context
5. Surface the verification status in any output or handoff to downstream systems

6. Protocol Versioning

The version 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 supported version: 1.0

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

API keys are available on Pro and HQ plans. To generate an API key:

1. Log in to your AEOBRO dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy your key — it will not be shown again

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 contact developers@aeobro.com.

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, contact: developers@aeobro.com