Integrate AetherID

Read a user's AetherID lens to give your app, AI tool, or agent the structured context they want it to operate with — tone, focus, project scope, reasoning anchors. No SDK to install; two HTTP endpoints.

Quickest path: MCP (Model Context Protocol)

The fastest way for an AI tool to talk to AetherID. After ~1 minute of setup, your Claude Desktop / Claude Code / Cursor session gets direct tool access to list, read, create, and update lenses — no copy-paste curl, no API key in the conversation.

Setup (one config entry per client)

{
  "mcpServers": {
    "aetherid": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://aetherid.ai/api/mcp",
        "--header", "Authorization:Bearer aeak_<your-key>"
      ]
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\ (Windows)
Claude Code: project-local .mcp.json or global ~/.claude/mcp.json
Cursor: Settings → MCP → Add new server (paste the JSON)

Get your API key by signing in at your AetherID profile → API key (owner) → Generate. Restart your AI client after saving the config.

Claude skill (optional, recommended)

An installable Agent Skill that teaches Claude the AetherID conventions — visibility tiers, the read-diff-confirm workflow, lens pairing, private-content handling — so it manages your profile correctly without re-explaining. Download aetherid-skill.zip. Claude Code / Desktop: unzip into ~/.claude/skills/. claude.ai: Settings → Capabilities → Skills → Upload. Grok has no skill system — use the connector above plus the conventions block in your custom instructions.

Tools exposed

list_lenses — enumerate your lenses (public + unlisted + private)
read_lens — raw JSON content of a lens
read_lens_markdown — rendered markdown view
create_lens — create a new lens
update_lens — PATCH content / name / description
get_profile — fetch JSON-LD profile

What integrations can do

Discover a user's lenses (public ones anonymously; unlisted and private ones too if they share an API key with you).
Fetch any lens as plain markdown — drop it straight into your AI's preferences / custom instructions / system prompt.
Switch lenses contextually — load the user's general-context lens for writing, switch to their project-context lens for project work.

Mutation (creating or editing lenses) is not in scope for this surface. That happens through the user's own /finalize flow or via per-lens improve tokens.

The integration model

User signs in at aetherid.ai/login and visits their own profile.
On their profile, the API key (owner) section lets them generate an aeak_… key. One per owner; regenerating replaces.
User pastes the key + their AetherID short name into your app's settings.
Your app calls AetherID with the key in the Authorization: Bearer header to list lenses, then fetches the chosen lens content (no auth needed for content — the URL is the capability).

REST API reference (fallback for non-MCP clients)

If the MCP path above doesn't fit your stack (e.g. you're building a Chrome plugin, CLI, or proprietary integration), use the REST endpoints below directly. Same auth model (Bearer aeak_ key).

List a user's lenses

GET https://aetherid.ai/api/profiles/<shortName>/lenses
Authorization: Bearer aeak_…

Returns { isOwner, lenses[] }. Without a valid Bearer, only visibility: 'public' lenses appear.

Fetch a lens (markdown)

GET https://aetherid.ai/<shortName>/aeid:<uuid>

Returns text/markdown. No auth — the AEID URL is the capability. Includes a Related lenses footer pointing to public siblings.

Fetch the profile JSON-LD

GET https://aetherid.ai/api/profiles/<shortName>

Returns the public AetherID profile as application/ld+json. Useful for displaying who the user is alongside their loaded lens.

Sample code (JavaScript)

List the user's lenses

const KEY = 'aeak_...'           // user's API key from their profile
const SHORT = 'leonard-cremer'   // user's AetherID shortName

const { lenses } = await fetch(
  `https://aetherid.ai/api/profiles/${SHORT}/lenses`,
  { headers: { Authorization: `Bearer ${KEY}` } }
).then(r => r.json())

// lenses: [{ aeid, type, name, description, visibility, url }, ...]

Fetch the chosen lens markdown

// Lens content is markdown. No auth needed — the URL is the capability.
const md = await fetch(`https://aetherid.ai${lens.url}`).then(r => r.text())

Wrap and inject into the target AI

const wrapped = [
  'You have been given the following AetherID lens to align your behaviour and context:',
  '',
  md,
  '',
  '---',
  '',
  'Now, with that context loaded, please help me with the following:',
  '',
].join('\n')

// Then: inject `wrapped` into your AI chat input, or set it as the
// system instruction / preferences field on the target tool.

Don't add headings above the lens markdown — it already opens with its own H1.

Threat model the integration should respect

The API key is a secret. Store in user-side secure storage. Never log it. Only ever sent as Authorization: Bearer to https://aetherid.ai.
Don't include the key when fetching public/unlisted lens content. No benefit — the lens URL is the capability. Private lenses are the exception: their URLs 404 without the owner's Bearer key (or the MCP tools).
An unlisted lens URL is a capability. Anyone with the URL gets the content. Treat the lens URLs you discover as the user's intentional share — don't redistribute them. Private lenses don't ride on URLs at all — owner auth only.
Per-domain or per-app preferences stay local. Don't sync the user's lens choice back to AetherID — that's their local decision.

Badge

Drop this link in your app's settings or about page to credit AetherID and link users to docs.

<a href="https://aetherid.ai/integrate" target="_blank" rel="noopener">
  Powered by AetherID
</a>

What's not here (yet)

OAuth-style consent flow — Phase 2. For now, the user pastes their key into your app manually.
Server-to-server "app registration" — Phase 2.
MCP server — Phase 2. Until then, treat AetherID as a regular HTTP API.
Signed VCs beyond email — Phase 2. Today, claim trust tiers are presented; verification of non-email claims is roadmap.