Third-Party Authentication

Demo

2.5-minute narrated walkthrough of the Authentication Intent flow — from creating an intent to receiving a session token.

Overview

Authentication 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.

The Flow

1. App creates an intent — POST /auth/intents returns a token, confirmation code, and status URL
2. App shows the code — e.g. BRTK-MXVZ displayed in the terminal
3. App opens browser — points to hydrogen.adom.inc/auth/intents/{token}
4. User logs in — email/password or Google OAuth (new!)
5. User enters the code — types the confirmation code from their app
6. Carbon creates a session — Application-scoped, linked to the intent
7. App receives the session token — via SSE (real-time) or short polling

Quick Start (JavaScript)

// 1. Create the intent
const res = await fetch('https://carbon.adom.inc/auth/intents', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ max_age: 7776000 }),  // 90-day session
});
const intent = await res.json();

// 2. Show code + open browser
console.log(`Code: ${intent.confirmation_code}`);
open(`https://hydrogen.adom.inc/auth/intents/${intent.token}`);

// 3. Wait for authentication via SSE
const es = new EventSource(`${intent.updates_url}/status`);
es.addEventListener('authenticated', (e) => {
  const { session_token } = JSON.parse(e.data);
  // Use session_token for authenticated API calls
});

Confirmation Code Format

• 8 uppercase consonants formatted as XXXX-XXXX
• No vowels (avoids accidental profanity)
• Case-insensitive verification, dashes/spaces stripped
• Prevents phishing — user must see the code from the real app

Intent Lifecycle

API Endpoints

Google OAuth Sign-In

Users 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.

Related

• OAuth Gateway — For integrating external OAuth providers (YouTube, GitHub, Slack) into Adom services. See the oauth skill for details.
• Carbon API — The backend that powers authentication intents, sessions, and user management.
• Hydrogen — The frontend that renders the login page, confirmation code entry, and Google OAuth flows.