Third-Party Authentication

Overview Files Versions Dependencies Discussions Activity

skill / 3rd-party-auth

Demo

3rd Party Auth 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

App creates an intent — POST /auth/intents returns a token, confirmation code, and status URL
App shows the code — e.g. BRTK-MXVZ displayed in the terminal
App opens browser — points to hydrogen.adom.inc/auth/intents/{token}
User logs in — email/password or Google OAuth (new!)
User enters the code — types the confirmation code from their app
Carbon creates a session — Application-scoped, linked to the intent
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

State	Description
Created	Waiting for user (15-min TTL)
Authenticated	User entered correct code, session linked
Consumed	App retrieved the session token
Expired	15 minutes elapsed without completion

API Endpoints

Method	Route	Description
`POST`	`/auth/intents`	Create a new intent (optional `max_age` body)
`GET`	`/auth/intents/{token}`	Retrieve intent details
`GET`	`/auth/intents/{token}/status`	Poll or SSE for auth status
`PATCH`	`/auth/intents/{token}`	Link user session (requires `confirmation_code`)

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.

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.