Zentro is the central identity and subscription platform that sits in front of your SaaS apps (ERP, CRM, HRMS, Billing and anything you connect). This guide is for hosts: the people who run Zentro for others.
There are two kinds of host, and this guide covers both:
| Host type | Who they are | Zentro role | What they do |
|---|---|---|---|
| Workspace host | The owner or admin of a client organization (tenant) | Owner or Admin | Creates the workspace, invites people, assigns roles, connects apps, manages the plan, seats and billing |
| Platform host | The team that operates the Zentro installation itself | Platform Super Admin | Installs and runs Zentro, registers SaaS apps as OAuth clients, defines plans, onboards and suspends tenants |
Tip: Press ⌘K (or Ctrl K) anywhere in the console to jump to any screen.
Quick start in 5 minutes#
- Create your workspace at
/register: your name, work email, a password, then your organization name and a plan. You get a 14-day trial right away. - Turn on two-step verification under Security. Your Zentro login opens every app, so protect it first.
- Invite your team under Members → Invite member. Pick a role for each person.
- Open an app from the App launcher. You land signed in, with your role in this organization.
- Pick a plan under Subscription before the trial ends.
Create your workspace#
Go to Start free trial on the home page. The sign-up has three short steps:
- You: full name, work email and a password (10+ characters with upper case, lower case and a number).
- Organization: the company name, an optional workspace slug (used in URLs and the
org_slugtoken claim) and your company domain. - Plan: Starter, Growth or Scale. Every plan starts as a free trial.
When you finish, Zentro automatically:
- creates the organization with status Trial,
- seeds the default roles Owner, Admin and Member,
- makes you the Owner,
- starts the subscription in the Trialing state,
- sends
organization.createdandsubscription.activatedwebhooks so connected apps can provision your tenant, - emails you a link to verify your address.
Invite your team#
Open Members and select Invite member.
- Enter the person's email and choose a role. The role applies the moment they accept.
- They receive an email link that expires after 48 hours. If no mail server is set up yet, the invite dialog shows the link so you can copy it.
- If the person already has a Zentro account (for another company, say), they confirm with their existing password. Otherwise they choose a name and password.
Seat limits. Active members, invited members and pending invitations all count toward your seats. When every seat is used, new invitations are blocked until you add a seat pack or upgrade (see Subscription, seats and add-ons).
Managing people. In the members table you can:
- change someone's role from the role dropdown (connected apps receive a
member.role_updatedwebhook), - Suspend a member (they can no longer sign in to this organization) or Reactivate them,
- Remove a member. Their sessions in this organization end immediately and apps receive
member.removed.
An organization always keeps at least one active Owner. Only Owners can make someone else an Owner.
Pending invitations are listed under the table, and you can revoke any of them.
Roles and permissions#
Every permission follows the pattern app:resource:action, for example erp:invoice:create, erp:report:view or crm:lead:delete.
System roles
| Role | Typical holder | Can do |
|---|---|---|
| Owner | Founder, IT head | Everything, including billing and ownership |
| Admin | Operations or IT admin | Everything except changing the plan, seats or add-ons |
| Member | Everyone else | View access in each included app |
System roles are shared by every organization and cannot be edited.
Custom roles
On Growth and above you can build your own roles under Roles & permissions → New custom role:
- Name the role (for example Accountant) and add a short description.
- Tick the permissions it needs, app by app. Use Select all for an app to grant everything in it.
- Save. Live permission checks use the new rules immediately; new access tokens carry them from the next sign-in or refresh (at most 15 minutes).
You can delete a custom role only when nobody holds it.
Zentro console permissions
| Permission | Unlocks |
|---|---|
zentro:member:view | Members and Roles screens |
zentro:member:invite | Inviting people and revoking invitations |
zentro:member:manage | Changing roles, suspending and removing members |
zentro:role:manage | Creating and editing custom roles |
zentro:billing:view | Subscription screen and invoices |
zentro:billing:manage | Changing plan, seats and add-ons |
zentro:audit:view | Audit log |
zentro:org:manage | Organization settings |
Working across organizations#
One person can belong to many organizations with a different role in each, for example Admin at Acme and Accountant at Globex.
Use the organization switcher at the top of the sidebar. Switching issues a new token scoped to the selected organization, without asking for your password again. Everything you see (members, plan, apps, audit log) then belongs to that organization only.
Zentro enforces tenant isolation on every request: a token for Acme can never read Globex data, even if you belong to both. The API answers 403 Forbidden on any mismatch.
Connected apps and single sign-on#
The App launcher shows every connected app. Apps included in your plan show Open with SSO; the rest show Not in plan.
When you open an app:
- The app sends you to Zentro (
/oauth/authorize) using OAuth 2.0 with PKCE. - If you are not signed in, you sign in once (with MFA if it is on).
- A consent screen shows the app, lets you pick which organization to use, and lists what the app receives: your name, email, organization, role and permissions for that app.
- You return to the app, already signed in.
Apps verify Zentro tokens on their own using the public keys at /.well-known/jwks.json, so they stay fast even under load.
The demo apps (ERP, CRM, HRMS, Billing, Insights) are wired to a built-in demo page that performs the full PKCE exchange and shows the verified token claims.
Subscription, seats and add-ons#
Open Subscription to see your plan, renewal date, seats, add-ons and invoices.
Change plan
Choose Upgrade or Downgrade on any plan. A preview shows the new price, a credit for unused time on your current plan, and the amount due today. Changes take effect immediately.
A downgrade is refused if you have more members than the new plan allows. Remove members or add seat packs first.
Seats
Use + 5 seats to buy a seat pack (prorated for the rest of the period), or − to remove one if the seats are free.
Module add-ons
Switch on extra apps that your plan does not include (for example HRMS on Growth). They are billed monthly and prorated.
Subscription lifecycle
| State | Meaning | What connected apps see (access_level) |
|---|---|---|
| Trialing | Free trial is running | full |
| Active | Paid and current | full |
| Past due | A payment failed or the trial ended unpaid | full, and a grace period starts |
| Grace period | Still unpaid, access continues (7 days by default) | full |
| Canceled | You canceled; the period ended | read_only |
| Expired | The grace period ended without payment | blocked, no apps enabled |
Cancel any time with Cancel at period end; you keep access until the period ends and can Resume before then.
Security#
Under Security each person can:
- Turn on two-step verification with an authenticator app (scan the QR code) or with codes sent by email.
- Change their password. Passwords are hashed with bcrypt.
- See active sessions. Each row is a device and app. Revoke signs that session out of Zentro and its apps.
- Sign out everywhere. This is Global Single Logout: every refresh token is revoked and apps receive
user.session_revoked.
What Zentro does automatically:
- Access tokens last 15 minutes; refresh tokens rotate on every use.
- If an old refresh token is ever replayed, Zentro treats it as theft and revokes the whole session family.
- Sign-in, code entry and password reset are rate limited against brute force.
- Resetting a password signs the user out everywhere.
As a host, encourage everyone with Owner or Admin roles to turn MFA on. The overview page reminds people who have not.
Audit log#
Audit log lists every sign-in (successful and failed), role change, membership change and subscription change, with the person, IP address and time. Filter by Sign-ins, Members, Roles, Billing, SSO or Organization.
Entries are immutable: nobody, including platform admins, can edit or delete them.
Organization settings and lifecycle#
Organization lets Owners and Admins edit the name, slug, domain and billing email, and copy the Organization ID (org_id) that apps use in API calls.
An organization is always in one of four states:
| Status | Meaning |
|---|---|
| Trial | New workspace on a free trial |
| Active | Paying customer |
| Suspended | Set by the platform host. Members cannot sign in to this organization and all its sessions are revoked |
| Archived | Offboarded. Kept for records, no access |
Platform hosts: install and run Zentro#
Requirements
- Node.js 20+ (22 LTS recommended) and npm
- PostgreSQL 14+ (row-level security is switched on by the migrations)
- Optional: Redis, when you run more than one API instance (shared entitlement, rate-limit and revocation caches)
Run the API as a non-superuser PostgreSQL role that owns the Zentro tables. Superusers bypass row-level security.
Backend (Node.js API)
# once: a database and a non-superuser owner
sudo -u postgres psql -c "CREATE ROLE zentro LOGIN PASSWORD 'zentro'"
sudo -u postgres psql -c "CREATE DATABASE zentro OWNER zentro"
cd backend
npm install
cp .env.example .env # DATABASE_URL=postgres://zentro:zentro@localhost:5432/zentro
npm run migrate # SQL migrations, including row-level security
npm run seed # platform defaults + demo tenants (ZENTRO_SEED_DEMO=false to skip demo)
npm run dev # http://localhost:8000
Signing keys are created automatically in storage/keys/ on first start. Demo accounts (local only) use the password Zentro@2026: admin@zentro.test (platform admin), owner@acme.test (Acme owner and Globex accountant), rahul@acme.test (member).
On a real install, skip the demo data and create your first platform admin:
ZENTRO_SEED_DEMO=false npm run seed
npx tsx src/cli.ts create-admin you@company.com "Your Name" 'A-strong-Passw0rd'
Frontend (Next.js portal)
cd frontend
npm install
cp .env.example .env.local # NEXT_PUBLIC_API_URL=http://localhost:8000
npm run dev # http://localhost:3000
Key environment variables
| Variable | Purpose | Default |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | postgres://zentro:zentro@localhost:5432/zentro |
ZENTRO_ISSUER | Public URL of the API, used as the token iss. HTTPS turns on Secure cookies | http://localhost:8000 |
ZENTRO_FRONTEND_URL | Public URL of the portal (login, consent, invites) | http://localhost:3000 |
CORS_ALLOWED_ORIGINS | Comma-separated origins allowed to call the API with credentials | the frontend URL |
ZENTRO_ENCRYPTION_KEY | 32 random bytes (base64) that encrypt MFA and webhook secrets at rest | generated into storage/keys/app.key |
ZENTRO_ACCESS_TTL | Access token lifetime in seconds | 900 |
ZENTRO_REFRESH_TTL | Refresh token lifetime in seconds | 2592000 |
ZENTRO_INVITE_TTL_HOURS | Invitation expiry | 48 |
ZENTRO_GRACE_DAYS | Grace period after a missed payment | 7 |
REDIS_URL | Shared cache for multiple instances | empty (in-memory) |
STRIPE_WEBHOOK_SECRET / RAZORPAY_WEBHOOK_SECRET | Payment webhook signature secrets | empty |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, MAIL_FROM | Email for invitations, OTPs and resets. Empty SMTP_HOST writes mail to storage/logs/mail.log | empty |
Deploy to a server from GitHub
The repository ships .github/workflows/deploy.yml and deploy/setup-server.sh. Every push to main runs the tests, then copies the release to your server over SSH and runs the setup script. The script only adds things named zentro and never changes other apps on the server:
- a private Node.js runtime in
/opt/zentro/node, and the code in/opt/zentro/releases(the newest 3 are kept, with automatic rollback if a release fails its health check) - a PostgreSQL role
zentro_appand databasezentroon the PostgreSQL that is already installed - two systemd services,
zentro-apiandzentro-web, listening on free ports on 127.0.0.1 only - one nginx site for your domain (checked with
nginx -tbefore reload) and, if you setLETSENCRYPT_EMAIL, an HTTPS certificate - generated secrets and a credentials file in
/etc/zentro(sudo cat /etc/zentro/CREDENTIALS.txt)
Add these in GitHub → Settings → Secrets and variables → Actions:
| Secret | Value |
|---|---|
DEPLOY_HOST | Server IP or host name |
DEPLOY_USER | SSH user with sudo |
DEPLOY_SSH_KEY | Private key of a deploy key whose public key is in the user's ~/.ssh/authorized_keys (recommended) |
DEPLOY_PASSWORD | Instead of a key: the SSH password (also used for sudo) |
LETSENCRYPT_EMAIL | Optional. Turns on HTTPS. Setting it accepts the Let's Encrypt Subscriber Agreement |
Optional repository variables: ZENTRO_DOMAIN (default zentro.folksflow.com) and ZENTRO_ADMIN_EMAIL (first platform admin login, default admin@<domain>). Extra settings such as SMTP go in /etc/zentro/api.local.env on the server and are picked up on the next deploy.
Production checklist
- PostgreSQL with a non-superuser owner role. Migrations enable row-level security on tenant tables, and the tenant middleware pins one connection per request with
app.current_org_idset. - HTTPS (TLS 1.2+) in front of both apps. Refresh cookies are
HttpOnly,SameSite=Lax, andSecurewhen the issuer is HTTPS. Serving the portal and API on one domain (as the deploy script does) is simplest. - Scheduler: the API runs it in-process (
ZENTRO_RUN_SCHEDULER=true): the lifecycle sweep hourly and key rotation monthly. With several instances, enable it on one only, or runnpm run sweepandnpm run rotate-keysfrom cron. - Several API instances need the same
ZENTRO_KEYS_PATHdirectory, the sameZENTRO_ENCRYPTION_KEY, andREDIS_URL. - Daily database backups with point-in-time recovery, plus a copy of the signing keys and encryption key.
-
NODE_ENV=productionandZENTRO_SEED_DEMO=false.
Key rotation
npm run rotate-keys # new key, prune keys older than 30 days
The newest key signs tokens; older keys stay in JWKS until they are pruned, so tokens already issued keep verifying.
Onboarding a tenant for a customer
Platform admin → Tenants → Onboard tenant: name, domain, billing email, owner name and email, plan, and trial or paid. If the owner has no account, Zentro creates one and shows a temporary password once.
Use the Lifecycle menu on each tenant to suspend, reactivate or archive it. Suspension revokes every session in that tenant and sends organization.suspended.
Plans
Platform admin → Plans defines price, billing cycle, seat limit, seat-pack price, included apps, trial length and JSON feature flags (for example {"custom_roles": true, "audit_retention_days": 180}). Apps read these flags from the entitlements API.
Connect a SaaS app#
1. Register the app
Platform admin → Applications → Register app:
- App key: short id such as
inventory. Every permission must start with it (inventory:item:create). - Redirect URIs: exact callback URLs. Anything else is rejected.
- Webhook URL: where Zentro sends events.
- Permissions: one
app:resource:actionper line.
Zentro shows the client_id, client_secret and webhook signing secret once. Store them in your app's secret manager. You can rotate either secret later.
Then add the app's key to the plans that should include it.
2. Sign users in (Authorization Code + PKCE)
Discovery document: GET {ZENTRO_ISSUER}/.well-known/openid-configuration.
GET /oauth/authorize
?client_id=zc_xxx
&redirect_uri=https://inventory.example.com/auth/callback
&response_type=code
&scope=openid profile email
&code_challenge=BASE64URL(SHA256(code_verifier))
&code_challenge_method=S256
&state=random
Exchange the code:
curl -X POST {ZENTRO_ISSUER}/oauth/token \
-d grant_type=authorization_code \
-d code=THE_CODE \
-d redirect_uri=https://inventory.example.com/auth/callback \
-d client_id=zc_xxx \
-d code_verifier=THE_VERIFIER
The response contains access_token (15 minutes), refresh_token and id_token. Refresh with grant_type=refresh_token; each refresh returns a new refresh token, and the old one stops working.
3. Verify tokens offline
// Node.js (jose)
import { createRemoteJWKSet, jwtVerify } from "jose";
const JWKS = createRemoteJWKSet(new URL("https://api.example.com/.well-known/jwks.json"));
const { payload } = await jwtVerify(token, JWKS, { issuer: "https://api.example.com", audience: "zc_xxx" });
// payload.org_id, payload.role, payload.scopes => ["inventory:item:create", ...]
// PHP (firebase/php-jwt)
$jwks = json_decode(file_get_contents('https://api.example.com/.well-known/jwks.json'), true);
$claims = \Firebase\JWT\JWT::decode($token, \Firebase\JWT\JWK::parseKeySet($jwks));
Token claims: sub (user id), email, name, org_id, org_slug, role, scopes (only this app's permissions), sid (session), aud (your client_id), exp.
4. Check permissions and entitlements live
Get a machine token with client credentials:
curl -X POST {ZENTRO_ISSUER}/oauth/token -u zc_xxx:CLIENT_SECRET -d grant_type=client_credentials
Then:
# Is this user allowed to do this right now?
curl -X POST {ZENTRO_ISSUER}/api/v1/authz/check -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"permission":"inventory:item:create","organization_id":"ORG_ID","user_id":"USER_ID"}'
# => {"allowed": false, "reason": "permission_missing"}
# What did this organization pay for?
curl {ZENTRO_ISSUER}/api/v1/organizations/ORG_ID/entitlements -H "Authorization: Bearer $TOKEN"
# => {"subscription_status":"active","access_level":"full","enabled_apps":["erp","crm"],
# "seats":{"limit":50,"used":42},"feature_flags":{...}}
# Who is in this organization?
curl {ZENTRO_ISSUER}/api/v1/organizations/ORG_ID/members -H "Authorization: Bearer $TOKEN"
Possible reason values: permission_missing, app_not_in_plan, subscription_expired, read_only_subscription, organization_suspended, user_suspended.
When access_level is read_only, allow viewing only. When it is blocked, show a renewal message.
5. Receive webhooks
Every event is a JSON POST with these headers:
X-Zentro-Event: member.role_updated
X-Zentro-Delivery: 0193f…
X-Zentro-Signature: t=1763650800,v1=<hex HMAC-SHA256 of "t.body" with your webhook secret>
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) throw new Error("bad signature");
Events: organization.created, organization.suspended, organization.activated, organization.archived, subscription.activated, subscription.updated, subscription.expired, member.added, member.role_updated, member.removed, user.session_revoked.
Use Send test on the application card to deliver a ping, and Platform admin → Webhooks to inspect every delivery.
6. Single logout
Send users to GET /oauth/logout?id_token_hint=ID_TOKEN&post_logout_redirect_uri=... to end their Zentro session and every connected app session. Listen for user.session_revoked to drop local sessions.
Payments (Stripe or Razorpay)#
- Create the subscription in your gateway and put the Zentro organization id in its metadata (
metadata.organization_idfor Stripe,notes.organization_idfor Razorpay). - Point the gateway webhook to:
- Stripe:
POST {ZENTRO_ISSUER}/api/v1/webhooks/stripe(eventsinvoice.paid,invoice.payment_failed,customer.subscription.deleted) - Razorpay:
POST {ZENTRO_ISSUER}/api/v1/webhooks/razorpay(eventssubscription.charged,subscription.halted,payment.failed,subscription.cancelled)
- Stripe:
- Set
STRIPE_WEBHOOK_SECRETorRAZORPAY_WEBHOOK_SECRET.
Zentro verifies the signature, records the invoice (idempotently), moves the subscription to Active, Past due or Canceled, and notifies connected apps.
Troubleshooting#
| Symptom | Likely cause | Fix |
|---|---|---|
| "Token is not scoped to this organization" (403) | The token belongs to a different org | Switch organization, or call the API with that org's token |
| "All seats are in use" (402) | Seat limit reached | Add a seat pack or upgrade |
| "Custom roles are available on Growth and above" | Plan feature flag custom_roles is off | Upgrade, or enable the flag on the plan |
| App shows "Not in plan" | The app key is not in the plan or add-ons | Add the module add-on or change plan |
invalid_redirect_uri during SSO | The callback URL is not allow-listed | Add the exact URI to the application |
PKCE verification failed | code_verifier does not match the challenge | Send the same verifier you hashed |
| Users get signed out unexpectedly | A refresh token was replayed, so the family was revoked | Check the audit log for auth.refresh_reuse_detected |
| Invites never arrive | SMTP_HOST is empty, so mail goes to storage/logs/mail.log | Configure SMTP, or copy the link from the invite dialog |
| Members of a tenant cannot sign in | Organization is suspended or archived | Platform admin → Tenants → set Active |
API reference#
| Method & path | Who calls it | Purpose |
|---|---|---|
GET /.well-known/openid-configuration | Apps | OIDC discovery |
GET /.well-known/jwks.json | Apps | Public keys for offline JWT checks |
GET /oauth/authorize | Browser | Start SSO (Authorization Code + PKCE) |
POST /oauth/token | Apps | Exchange code, refresh, or client credentials |
POST /oauth/revoke | Apps | Revoke a refresh token family |
GET/POST /oauth/logout | Browser / apps | Global single logout |
POST /api/v1/auth/switch-organization | Portal | New token for another organization |
GET /api/v1/userinfo | Apps | Profile, active organization, role |
POST /api/v1/authz/check | Apps | Live permission check |
GET /api/v1/organizations/{org_id}/entitlements | Apps | Plan, apps, seats, feature flags |
GET /api/v1/organizations/{org_id}/members | Apps / portal | List members |
POST /api/v1/organizations/{org_id}/members | Portal | Invite a member |