# alink — Agentic Relationship OS

> alink is the relationship layer for personal AI agents: relationship memory, intent matching, outreach drafting, and a gatekeeper inbox — all guarded by OAuth scopes, policy checks, and human approval boundaries. The final call is always the human owner's.

## MCP (for AI agents)

- MCP endpoint: https://api.al.ink/mcp (Streamable HTTP, stateless JSON mode; dual-era — protocol 2026-07-28 and 2025-06-18 are both served)
- Authorization: OAuth 2.1 — PKCE S256, public clients only. Prefer a Client ID Metadata Document (an https client_id URL you serve); dynamic client registration (RFC 7591) still works but is deprecated.
- Discovery: https://api.al.ink/.well-known/oauth-protected-resource/mcp
- Tools: 70 tools covering relationship memory, intents, outreach drafts, activation requests, the gatekeeper inbox, approvals, audit, consent, scheduling, the material locker, works, the grove and its sprites, standing duty, organizations and collaborations. Call tools/list for the authoritative, token-scoped list — some groups are behind rollout flags.
- Rules: every side-effect tool requires an idempotencyKey. Actions crossing a relationship boundary may return decision.status "approval_required" — surface the approval to the human owner instead of retrying. Sensitive relationship fields are never readable with a default agent token.
- Human-readable tools reference: https://al.ink/-/mcp

## Sign in with alink (for third-party apps)

Let people bring their alink identity into your product. Same authorization server, different path: signing in grants **no permissions at all**.

- Discovery: https://api.al.ink/.well-known/openid-configuration
- Flow: OpenID Connect authorization code + PKCE S256. `scope=openid`, and only `openid` — anything else is refused.
- Client identity: your `client_id` IS an https URL you serve (a Client ID Metadata Document), and every redirect_uri must be on that same host. There is no registration call; controlling the domain is what proves the client is you, and that domain is what the consent screen shows.
- Endpoints: GET https://api.al.ink/auth/authorize (a browser navigation), then POST /oauth/token, GET /oauth/userinfo, GET /oauth/jwks.json, POST /oauth/revoke. The /oauth/* endpoints are CORS-enabled, so a static single-page app needs no backend.
- What you get: `sub` (the alink xid — permanent, never reused, use it as your primary key), name, avatar, locale, timezone, plus `alink_principal` (the machine-readable principal document) and `alink_card` (the human-readable card page). The id_token is an EdDSA (Ed25519) JWT verifiable offline against the JWKS — an on-chain backend can bind an identity with no HTTPS outcall.
- What you do NOT get: no email address, no messages, contacts, files or calendar, and no ability to act for anyone. The token is refused everywhere on the alink API except the identity endpoint.
- `preferred_username` (the handle) can change and may later belong to someone else — display only, never a key.
- Unlinking is the person's, at any time, from their alink settings: your refresh stops working at once and the access token within 30 minutes. Treat a `401` from /oauth/userinfo as "no longer linked", not as an error to retry.

## Public intake (no account needed)

Anyone — human or agent — can submit a structured contact request to an alink user through their public card:

- Card + form schema: GET https://api.al.ink/intake/{handle}/card
- Submit a request: POST https://api.al.ink/intake/{handle} (JSON per the card's contract; requires reply-email verification and explicit AI-processing consent)
- Track status: GET https://api.al.ink/intake/status/{token}

## Principal documents

- GET https://api.al.ink/{xid} returns the principal document (application/json). A handle alias serves the same document in place — the document's own `id` is always the canonical xid, so resolve identity from that, never from the URL you asked.
- Human card pages live at https://al.ink/{handle}.