Third-Party Authentication

{
  "schema_version": 1,
  "type": "skill",
  "slug": "3rd-party-auth",
  "title": "Third-Party Authentication",
  "brief": "Sign in with Adom — let users authenticate to your app using their Adom account via Authentication Intents with confirmation codes. Covers the full flow, API reference, code examples, and Google OAuth",
  "version": "1.0.0",
  "tags": [],
  "license": "MIT",
  "sample_prompts": [
    {
      "label": "Sign in with Adom",
      "prompt": "How do I add 'Sign in with Adom' to my app?"
    },
    {
      "label": "Create intent",
      "prompt": "Show me how to create an authentication intent"
    },
    {
      "label": "Auth flow code",
      "prompt": "Give me a complete JavaScript example of the auth intent flow"
    },
    {
      "label": "Confirmation codes",
      "prompt": "How do confirmation codes prevent phishing?"
    },
    {
      "label": "Poll vs SSE",
      "prompt": "Should I use polling or SSE to wait for authentication?"
    },
    {
      "label": "Session tokens",
      "prompt": "How do I use the session token after authentication?"
    },
    {
      "label": "Google OAuth",
      "prompt": "How does Google sign-in work with authentication intents?"
    },
    {
      "label": "Intent API",
      "prompt": "What are all the authentication intent API endpoints?"
    }
  ],
  "source_path": "SKILL.md",
  "readme": "## Demo\n\n![3rd Party Auth Demo](skills/3rd-party-auth/demo.webm)\n\n2.5-minute narrated walkthrough of the Authentication Intent flow — from creating an intent to receiving a session token.\n\n---\n\n## Overview\n\nAuthentication Intents let any application add \"Sign in with Adom\" functionality. The flow uses **confirmation codes** to prevent phishing — the user must verify that a code shown in their application matches what they see in the browser.\n\n### The Flow\n\n1. **App creates an intent** — `POST /auth/intents` returns a token, confirmation code, and status URL\n2. **App shows the code** — e.g. `BRTK-MXVZ` displayed in the terminal\n3. **App opens browser** — points to `hydrogen.adom.inc/auth/intents/{token}`\n4. **User logs in** — email/password or Google OAuth (new!)\n5. **User enters the code** — types the confirmation code from their app\n6. **Carbon creates a session** — Application-scoped, linked to the intent\n7. **App receives the session token** — via SSE (real-time) or short polling\n\n### Quick Start (JavaScript)\n\n```javascript\n// 1. Create the intent\nconst res = await fetch('https://carbon.adom.inc/auth/intents', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ max_age: 7776000 }),  // 90-day session\n});\nconst intent = await res.json();\n\n// 2. Show code + open browser\nconsole.log(`Code: ${intent.confirmation_code}`);\nopen(`https://hydrogen.adom.inc/auth/intents/${intent.token}`);\n\n// 3. Wait for authentication via SSE\nconst es = new EventSource(`${intent.updates_url}/status`);\nes.addEventListener('authenticated', (e) => {\n  const { session_token } = JSON.parse(e.data);\n  // Use session_token for authenticated API calls\n});\n```\n\n### Confirmation Code Format\n\n- **8 uppercase consonants** formatted as `XXXX-XXXX`\n- No vowels (avoids accidental profanity)\n- Case-insensitive verification, dashes/spaces stripped\n- Prevents phishing — user must see the code from the real app\n\n### Intent Lifecycle\n\n| State | Description |\n|-------|-------------|\n| Created | Waiting for user (15-min TTL) |\n| Authenticated | User entered correct code, session linked |\n| Consumed | App retrieved the session token |\n| Expired | 15 minutes elapsed without completion |\n\n### API Endpoints\n\n| Method | Route | Description |\n|--------|-------|-------------|\n| `POST` | `/auth/intents` | Create a new intent (optional `max_age` body) |\n| `GET` | `/auth/intents/{token}` | Retrieve intent details |\n| `GET` | `/auth/intents/{token}/status` | Poll or SSE for auth status |\n| `PATCH` | `/auth/intents/{token}` | Link user session (requires `confirmation_code`) |\n\n### Google OAuth Sign-In\n\nUsers can now sign in to Hydrogen with their Google account. This is built into the login page — 3rd party apps get it for free when users are directed to the Hydrogen login flow. New Google users are prompted to choose a username before their account is created.\n\n### Related\n\n- **OAuth Gateway** — For integrating external OAuth providers (YouTube, GitHub, Slack) into Adom services. See the `oauth` skill for details.\n- **Carbon API** — The backend that powers authentication intents, sessions, and user management.\n- **Hydrogen** — The frontend that renders the login page, confirmation code entry, and Google OAuth flows.\n",
  "author": {
    "name": "Kyle Bergstedt",
    "email": "[email protected]"
  },
  "visibility": {
    "public": true
  },
  "hero": null,
  "discovery_triggers": [],
  "discovery_pitch": null,
  "metadata": {},
  "created_at": "2026-05-28T05:29:34.040Z",
  "updated_at": "2026-05-28T05:29:34.040Z",
  "sub_skills": [],
  "parent_app": null
}