@urantia/auth - OAuth Authentication

Install

npm install @urantia/auth

Overview

@urantia/auth handles the OAuth Authorization Code flow with accounts.urantiahub.com. Users sign in once and authorize your app to access their data (bookmarks, notes, reading progress, preferences). Your app receives an access token (7-day expiry) that you pass to @urantia/api for authenticated endpoints. The most common flow for web apps:

Start sign-in

Redirect the user to accounts.urantiahub.com:

import { UrantiaAuth } from '@urantia/auth'

const auth = new UrantiaAuth({
  appId: 'my-app',
  redirectUri: 'https://myapp.com/callback',
})

await auth.signIn({ mode: 'redirect', scopes: ['bookmarks', 'notes'] })
// → user is redirected to accounts.urantiahub.com

Handle the callback

On your redirect URI page, complete the flow:

const auth = new UrantiaAuth({
  appId: 'my-app',
  redirectUri: 'https://myapp.com/callback',
})

const session = await auth.handleCallback()
// session.user.id, session.user.email, session.accessToken

Use the token

Pass the access token to @urantia/api:

import { UrantiaAPI } from '@urantia/api'

const api = new UrantiaAPI({ token: session.accessToken })
const { data: bookmarks } = await api.me.bookmarks.list()

For desktop apps or when you don’t want to navigate away:

const auth = new UrantiaAuth({
  appId: 'my-app',
  redirectUri: 'https://myapp.com/callback',
})

// Opens popup window — resolves when user completes sign-in
const session = await auth.signIn({ scopes: ['bookmarks', 'notes'] })
console.log(session.user.email, session.accessToken)

Server-Side Token Exchange

For backend environments where you already have an authorization code and app secret:

import { UrantiaAuth } from '@urantia/auth'

const auth = new UrantiaAuth({
  appId: 'my-app',
  appSecret: process.env.URANTIA_APP_SECRET,
})

const session = await auth.signIn({ code: authorizationCode })

Server-side exchange is more secure because the app secret never leaves your server. The demo app uses this approach — the browser handles the redirect, and a server-side API route exchanges the code.

Session Management

Sessions are automatically persisted in localStorage and restored on page load.

// Check current session (returns null if not signed in or expired)
const session = auth.getSession()

// Get just the token
const token = auth.getToken()

// Listen for auth state changes
const unsubscribe = auth.onAuthStateChange((session) => {
  if (session) {
    console.log('Signed in:', session.user.email)
  } else {
    console.log('Signed out')
  }
})

// Sign out (clears localStorage)
auth.signOut()

Available Scopes

When calling signIn(), you can request specific scopes:

Scope	Access
`profile`	Read your profile information
`bookmarks`	Read and write bookmarks
`notes`	Read and write notes
`reading-progress`	Read and write reading progress
`preferences`	Read and write preferences
`app-data`	Read and write your app data

await auth.signIn({ scopes: ['profile', 'bookmarks', 'notes'] })

Options

Option	Type	Required	Default
`appId`	`string`	Yes	—
`appSecret`	`string`	Server only	—
`redirectUri`	`string`	Browser	—
`loginUrl`	`string`	No	`https://accounts.urantiahub.com`
`apiUrl`	`string`	No	`https://api.urantia.dev`

Security

PKCE (Proof Key for Code Exchange) — used automatically for browser flows to prevent authorization code interception
State parameter — CSRF protection via random state verification
Token expiry — access tokens expire after 7 days; expired sessions are automatically cleared
App secrets — never stored in the browser; use server-side token exchange for production apps

Registering Your App

To use @urantia/auth, you need a registered OAuth app.

Go to accounts.urantiahub.com/apps and sign in with your Urantia account (email or Google).

Create a new app

Click Create app and fill in:

App ID — a unique slug (e.g. my-reading-app). Lowercase letters, numbers, and hyphens.
App Name — shown to users on the consent screen
Redirect URIs — URLs where users are sent after authorization (e.g. http://localhost:3000/callback for local dev)
Scopes — which permissions your app needs

Save your credentials

After creation, you’ll see your App ID and App Secret. The secret is only shown once — save it somewhere secure.

Your app secret is only displayed once. If you lose it, you can rotate it from the app details page, but any existing integrations using the old secret will break.

Start building

Use your App ID to initialize the SDK:

import { UrantiaAuth } from '@urantia/auth'

const auth = new UrantiaAuth({
  appId: 'my-reading-app',
  redirectUri: 'http://localhost:3000/callback',
})

You can manage your apps, rotate secrets, and delete apps at any time from the Developer Portal.

Getting Started

Data

SDKs

Integrations

Open Source

Donate

Legal

@urantia/auth - OAuth Authentication

Install

Overview

Server-Side Token Exchange

Session Management

Available Scopes

Options

Security

Registering Your App

​Install

​Overview

​Browser Sign-In (Redirect)

​Browser Sign-In (Popup)

​Server-Side Token Exchange

​Session Management

​Available Scopes

​Options

​Security

​Registering Your App

Install

Overview

Browser Sign-In (Redirect)

Browser Sign-In (Popup)

Server-Side Token Exchange

Session Management

Available Scopes

Options

Security

Registering Your App