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.

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.

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 Client Portal and connect

Go to Client portal, 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 AI integration spec — downloadable Markdown with env contract, SDK steps, and validation checklist.

AI integration spec Developers & AI

Use this when a customer dev team — or an AI coding agent — needs to wire an app to Roalla Auth Hub. The spec covers prerequisites, environment variables, BFF/PKCE flow, Express vs Next.js paths, required routes, validation, and common failures.

Download Markdown View in browser

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

Integrate this app with Roalla Auth Hub using the spec at {origin}/downloads/AI_CUSTOMER_INTEGRATION.md — configure AUTH_URL, AUTH_CLIENT_ID, APP_URL, mount @roalla/auth BFF routes, and validate with roalla-auth doctor.

What's inside

Prerequisites — hub URL, client ID, env snippet, portal token
10-step customer checklist — ordered gates from env → SDK → test → deploy
Environment contract — required JSON schema + example .env
Auth flow — PKCE + BFF token exchange sequence
Integration paths — Express starter, Next.js starter, existing app
SDK reference — wireRoallaAuth, AppAuth, Next handlers
Definition of done — checklist before go-live
Troubleshooting — invalid return_url, CORS, 401, prod vs local

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 Client Portal

Open Client portal, 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 Client portal 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 Client portal 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

Customer quick steps Client projects

1 Receive your invite token

2 Open the Client Portal and connect

3 Run automated onboarding

4 Save your portal token and env snippet

5 Verify sign-in works

AI integration spec 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 Client Portal

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`