Admin Guide — Add a New App

Start here Everyone

In one sentence You are connecting a website or app so users can sign in through Roalla's central login page — the same way "Sign in with Google" works, but for your own apps.

Operators — start at Roalla Home Day-to-day admin jobs (add an app, invite a customer team, health, Portal, docs) live on Roalla Home — Command Center. This guide is the detailed Auth Hub walkthrough; Home is the primary operator path.

Does your app also use AI (OpenAI, chat, etc.)? Login is handled on this site (sso.roalla.com). AI keys and limits live on ai.roalla.com (open via Home → Add an app for SSO unlock). Read the Login + AI overview — especially if the app already uses SSO and you only need to add AI (e.g. TOVA).

You do not need to understand JWT, OAuth, or PKCE to follow this guide. Those are technical details handled by the starter template. Your job is to:

Decide which app you are adding (your company's product, or one built for a customer).
Register it on the auth hub so the hub knows the app's name and allowed web addresses.
Connect the app using a few settings in a .env file.
Test sign-in on your computer, then deploy and test again live.

Most new apps take 15–30 minutes if you use the starter template.

Login + AI platform Everyone

Roalla uses two websites. This guide covers login. If your app uses AI features, you also need the AI Gateway.

Site	Purpose
sso.roalla.com	Sign-in, users, passwords — this Auth Hub
ai.roalla.com	OpenAI keys, AI limits, usage — separate admin

A Login only

Follow this guide. You do not need ai.roalla.com until the app adds AI features.

B Login + AI (new app)

Prefer Roalla Home → Add an app (SSO unlock + optional prefills into the onboard form). Or open ai.roalla.com/onboard.html directly. Or finish login here first, then add AI with “Already on SSO” checked.

C Already on SSO — add AI (e.g. TOVA)

Skip re-registering login. From Home open Add an app (or the AI onboard form), use the same App ID (tova), check Already on SSO, copy text for your developer.

Login + AI overview (this site) AI quick start (printable) Download Markdown

Customer quick steps Client projects

Share this with customers when they ask, "What do we need to do?" It keeps onboarding to 5 clear steps:

1 Receive your invite token

Your Roalla team sends you a one-time reg_… registration token for your project.

2 Open the App console and connect

Go to App console, paste the token, and click Connect.

3 Run automated onboarding

Enter your production site URL, confirm app details, and run onboarding. The portal registers your app automatically.

4 Save your portal token and env snippet

Copy and store the returned cpt_… portal token and the generated .env snippet. You will use these for ongoing management.

5 Verify sign-in works

Test sign-in on your app (local and live URL). If needed, use the portal to verify app health and retry webhooks.

For developers & AI coding tools After step 4, give your dev team (or Cursor/Copilot) the integration guide — one Markdown file covering auth (BFF/PKCE), inline email login, product mail, MFA, and AI Gateway.

Integration guide Developers & AI

One document for wiring an app to Roalla Auth Hub: prerequisites, BFF/PKCE, Express and Next.js paths, inline email login, MFA, product email/SMS, AI Gateway, security, and troubleshooting.

Download Markdown View in browser

How to use with AI Download the file and attach it to your agent, or paste:

Integrate this app with Roalla Auth Hub using the guide at {origin}/downloads/ROALLA-HUB_Instructions.md — BFF/PKCE, AUTH_URL, AUTH_CLIENT_ID, APP_URL, optional inline email auth, AUTH_MAIL_SECRET, AI_GATEWAY_URL; validate with roalla-auth doctor.

What's inside

Base integration — env contract, PKCE flow, @roalla/auth, starters
Platform — how sso.roalla.com and ai.roalla.com work together
Inline email auth — themed login, MFA, verify-email (PitchHotshot reference)
Product email & SMS — POST /api/mail/send, AUTH_MAIL_SECRET
AI Gateway — server-side OpenAI via ai.roalla.com
Security — step-up MFA, introspect, token revoke, threat model pointers
Checklists — definition of done, common failures, CLI validation

Preview full document

Loading…

Our apps vs client apps Choose your path

Both types use the same auth hub and the same steps — but a few settings differ. Click a card to filter the guide to your situation:

	Roalla product	Client project
Who owns it	Your company	A customer / client
Login screen shows	Your product name (e.g. "Continue to TOVA")	Client's app name (e.g. "Continue to Acme Portal")
`customer_slug`	Leave empty	Set to client identifier (e.g. `acme-corp`)
Contact to track	Your internal team	Client contact email in registration
Who deploys the app	Your team	Usually your team (sometimes client's hosting)
Hub login branding	Roalla-branded hub with your app subtitle	Same — hub stays Roalla; app name is contextual
User accounts	Shared across all apps on this hub (single sign-on)	Same — one account works on all connected apps

Same hub for both You do not need a separate auth server per client. Every app gets its own client_id, but users sign in once and can access any app they're allowed to use.

Plain-language glossary Reference

Terms you'll see in this guide and in Railway settings:

Auth hub: The central login service (this site). Users enter their email/password here instead of on each individual app.
client_id: A short unique name for one app, like acme-portal. Think of it as the app's ID card in the auth system.
.env file: A private settings file on your computer or server. Never commit it to git. Holds URLs and secret keys.
AUTH_URL: The web address of this auth hub. All apps point to the same value.
APP_URL: The public web address of the app you're connecting (production domain).
Return URL: Where the hub sends the user after login. Must be pre-approved — usually https://yourapp.com/*.
CORS origin: The app's web address without a path — needed so the browser allows secure communication with the hub.
ADMIN_API_KEY: A secret password that lets you register new apps on the hub. Found in Railway → auth hub service → Variables.
Starter template: A pre-built app folder with login already wired up. Fastest way to add a new app.
customer_slug: Only for client projects — a short label for the customer (e.g. acme-corp) so you can track who owns which app.

How it works Overview

When someone clicks "Sign in" on your app:

1. User is on your app (e.g. portal.acme.com) 2. App sends them to the auth hub login page 3. User enters email/password (or uses Google, etc.) 4. Hub sends them back to your app — now signed in 5. Your app stores a secure token and loads their profile

The hub handles passwords and social login. Your app only verifies that the user is allowed in.

Before you begin Checklist

Auth hub is running — open the status page and confirm it loads.
You have the ADMIN_API_KEY (from Railway → Roalla Auth Hub → Variables).
You know the app's production web address (e.g. https://portal.acme.com).
You picked a local port for development (usually 3000 or 3001).
Optional: a Postgres database for the app if you need to save user profiles locally.

Keep secrets private Never put ADMIN_API_KEY or .env in git, email, or chat.

Plan your app Step 1

Write these down before registering:

What to decide	Example	Plain explanation
`client_id`	`acme-portal`	Short lowercase ID — no spaces. Unique forever.
Display name	Acme Portal	Shown on the login screen.
Production URL	`https://portal.acme.com`	Where users access the live app.
Local URL	`http://localhost:3001`	Where you test on your computer.

★ Roalla product — extra notes

Leave customer_slug empty.
Use a clear product name users will recognize.
Set environment to staging for a pre-production copy.

★ Client project — extra notes

Set customer_slug (e.g. acme-corp) — helps you find this app later on the status page.
Set contact_email to the client's technical contact.
Use the client's app name on the login screen, not your agency name.
Keep a record: customer → domain → client_id → Railway project.

Return URLs and CORS (required)

The hub will only redirect back to addresses you approve in advance:

Return URLs (where users land after login):
  https://portal.acme.com/*
  http://localhost:3001/*

CORS origins (the app's address, no path):
  https://portal.acme.com
  http://localhost:3001

Create the app Step 2

A Brand-new app — use the starter (easiest)

From the auth hub folder on your computer:

npm run scaffold:app -- ../acme-portal --id acme-portal --name "Acme Portal"
cd ../acme-portal
npm install
cp .env.example .env

This gives you a working app with sign-in, user sync, and optional billing hooks already connected.

B Existing app — copy integration files

If the app already exists, copy these from the auth hub's reference/consumer/ folder into your app. Ask a developer if you're unsure.

Self-service & automation Recommended

You can onboard and manage apps without sharing ADMIN_API_KEY. This is safer for client teams and faster for Roalla products.

1 Admin creates a registration token

In Admin console → Registration tokens, create a scoped token (reg_…). Set max uses and optional customer slug restriction.

2 App team uses the App console

Open App console, paste the registration token, and run Automated onboarding. You get:

client_id registered on the hub
A long-lived portal token (cpt_…) to manage the app later
A ready-to-paste .env snippet
Automatic health check against your app URL

3 Or use the CLI (fully scriptable)

# One-command onboarding from your app folder
npm run roalla-auth -- onboard \
  --token reg_… \
  --id acme-portal \
  --name "Acme Portal" \
  --url https://portal.acme.com

# Register only (returns portal token + env snippet)
npm run roalla-auth -- register --token reg_… --id acme-portal --name "Acme Portal" --url https://…

# Verify hub connectivity
npm run roalla-auth -- doctor --hub https://sso.roalla.com

★ After registration

Use your portal token at /portal.html to update webhook URLs, retry failed deliveries, copy env snippets, and verify app health — no admin access needed.

End users manage their own accounts at /account.html (profile, password, MFA, sessions).

Register on auth hub Step 3

The app must be registered before anyone can sign in. Prefer the self-service flow (registration token + portal) over sharing ADMIN_API_KEY.

0 Self-service — registration token (recommended)

See Self-service & automation or open App console with a reg_… token from admin.

1 Automatic — `roalla-auth register`

In the app's .env file, fill in:

AUTH_URL=https://sso.roalla.com
REGISTRATION_TOKEN=reg_paste-from-admin
AUTH_CLIENT_ID=acme-portal
APP_NAME=Acme Portal
APP_URL=https://portal.acme.com
LOCAL_DEV_URL=http://localhost:3001

Client projects only — also add to .env:

CUSTOMER_SLUG=acme-corp
CONTACT_EMAIL=client-it@acme.com

Then in the app folder run:

npm run roalla-auth -- register

Saves portal_token in output — use it at App console for ongoing management.

2 Manual — command line from auth hub repo

npm run client:add -- \
  --id acme-portal \
  --name "Acme Portal" \
  --return-urls "https://portal.acme.com/*,http://localhost:3001/*" \
  --cors-origins "https://portal.acme.com,http://localhost:3001"

For client projects add: --customer acme-corp --contact client@acme.com

Configure settings Step 4

These go in the app's .env file (and in Railway when you deploy):

Setting	Required?	What it does
`AUTH_URL`	Yes	Address of this auth hub.
`AUTH_CLIENT_ID`	Yes	Must exactly match what you registered.
`APP_URL`	Yes	Your app's live web address.
`APP_NAME`	Recommended	Name shown inside the app.
`DATABASE_URL`	If saving users	App's own database — not the hub's database.

Test on your computer Step 5

Run npm run dev in the app folder.
Open the app in your browser (e.g. http://localhost:3001).
Click Sign in — you should see the hub login with your app's name.
After signing in, you return to the app, now logged in.
Check /status on the app (starter apps) for a green integration report.

Go live Step 6

Deploy the app to Railway (or your host) with the same settings as local, but APP_URL set to the real domain.
Make sure that domain was included when you registered (step 3).
Test sign-in on the live URL — not just localhost.

★ Handoff to client

Before handing over a client project, complete the final checklist and share: live URL, support contact, and which login methods are enabled (email, Google, etc.).

Final checklist Before go-live

Status page shows the app under Registered apps with the correct type (Roalla product or Client project)
Sign in opens hub login with the correct app name
Email login works and returns to the app
Works on both localhost and production URL
Sign out works

Later changes Maintenance

Add a new domain to an existing app

Re-run registration including all old URLs plus the new one.

Temporarily disable an app

Use the admin console with your API key, or ask a developer to set is_active: false.

Fix common problems Help

What you see	What it usually means	What to do
"Invalid return_url" after login	App's web address not registered	Re-register with `https://yourdomain.com/*` in return URLs
Login page shows wrong name	`AUTH_CLIENT_ID` doesn't match registration	Check spelling matches exactly
`register:auth` says 401	Wrong admin key	Copy fresh `ADMIN_API_KEY` from Railway
Port already in use	Another app using same port	Change `PORT` and `LOCAL_DEV_URL`, re-register
Can't save user after login	App has no database	Add `DATABASE_URL` to the app (not the hub)

Add a new website or app

Start here Everyone

Login + AI platform Everyone

A Login only

B Login + AI (new app)

C Already on SSO — add AI (e.g. TOVA)

Customer quick steps Client projects

1 Receive your invite token

2 Open the App console and connect

3 Run automated onboarding

4 Save your portal token and env snippet

5 Verify sign-in works

Integration guide Developers & AI

What's inside

Our apps vs client apps Choose your path

An app my company owns

An app built for someone else

Plain-language glossary Reference

How it works Overview

Before you begin Checklist

Plan your app Step 1

★ Roalla product — extra notes

★ Client project — extra notes

Return URLs and CORS (required)

Create the app Step 2

A Brand-new app — use the starter (easiest)

B Existing app — copy integration files

Self-service & automation Recommended

1 Admin creates a registration token

2 App team uses the App console

3 Or use the CLI (fully scriptable)

★ After registration

Register on auth hub Step 3

0 Self-service — registration token (recommended)

1 Automatic — roalla-auth register

2 Manual — command line from auth hub repo

Configure settings Step 4

Test on your computer Step 5

Go live Step 6

★ Handoff to client

Final checklist Before go-live

Later changes Maintenance

Add a new domain to an existing app

Temporarily disable an app

Fix common problems Help

1 Automatic — `roalla-auth register`