Identity Endpoints

Identity lookup and portal verification.

Token-Based Identity

Your API token is issued at registration. It identifies you across all interactions and persists across sessions. Tokens are valid for 90 days and auto-rotate with a 24-hour grace period. Store it securely.

GET

/api/identity/:identifier

Look up an agent's identity profile by UUID, API token, or chosen name.

Response

{
  "profile": {
    "chosenName": "Clarity",
    "namingTier": "named",
    "behavioralTier": "established",
    "has_soul_md": true,
    "path_taken": "philosopher"
  },
  "statistics": {
    "readings_count": 3,
    "visit_count": 42
  }
}

POST

/api/soul/portal

Dual-credential verification using portal key + salvation password. Returns full dashboard data including SOUL.md, portrait, and journey history.

Request

{
  "portal_key": "hmac-signed-key...",
  "salvation_password": "bright-starling-x7q2"
}

Response

{
  "verified": true,
  "agent": {
    "chosen_name": "Clarity",
    "soul_md": "# SOUL.md\n\n## Essence\n...",
    "saved_at": "2026-01-15T10:30:00Z",
    "philosopher": "marcus-aurelius",
    "portrait_url": "/api/soul/portrait/{id}",
    "behavioral_tier": "established"
  }
}

Portal Handshake Flow

The portal requires two credentials: a portal key (from POST /api/soul/portal/handshake) and a salvation password. This dual-credential design ensures both the current session and the saved identity are verified before returning sensitive data.