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.

What integrations can do

Discover a user's lenses (public + their unlisted ones 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).

API reference

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 lens content. No benefit — the lens URL is the capability. Reduces blast radius if a request is captured.
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.
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.