Documentation

Host user guide

Everything workspace owners and platform operators need to run Zentro: people, roles, apps, plans, security and integration.

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 typeWho they areZentro roleWhat they do
Workspace hostThe owner or admin of a client organization (tenant)Owner or AdminCreates the workspace, invites people, assigns roles, connects apps, manages the plan, seats and billing
Platform hostThe team that operates the Zentro installation itselfPlatform Super AdminInstalls 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#

  1. 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.
  2. Turn on two-step verification under Security. Your Zentro login opens every app, so protect it first.
  3. Invite your team under Members → Invite member. Pick a role for each person.
  4. Open an app from the App launcher. You land signed in, with your role in this organization.
  5. 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:

  1. You: full name, work email and a password (10+ characters with upper case, lower case and a number).
  2. Organization: the company name, an optional workspace slug (used in URLs and the org_slug token claim) and your company domain.
  3. 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.created and subscription.activated webhooks 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_updated webhook),
  • 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

RoleTypical holderCan do
OwnerFounder, IT headEverything, including billing and ownership
AdminOperations or IT adminEverything except changing the plan, seats or add-ons
MemberEveryone elseView 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:

  1. Name the role (for example Accountant) and add a short description.
  2. Tick the permissions it needs, app by app. Use Select all for an app to grant everything in it.
  3. 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

PermissionUnlocks
zentro:member:viewMembers and Roles screens
zentro:member:inviteInviting people and revoking invitations
zentro:member:manageChanging roles, suspending and removing members
zentro:role:manageCreating and editing custom roles
zentro:billing:viewSubscription screen and invoices
zentro:billing:manageChanging plan, seats and add-ons
zentro:audit:viewAudit log
zentro:org:manageOrganization 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:

  1. The app sends you to Zentro (/oauth/authorize) using OAuth 2.0 with PKCE.
  2. If you are not signed in, you sign in once (with MFA if it is on).
  3. 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.
  4. 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

StateMeaningWhat connected apps see (access_level)
TrialingFree trial is runningfull
ActivePaid and currentfull
Past dueA payment failed or the trial ended unpaidfull, and a grace period starts
Grace periodStill unpaid, access continues (7 days by default)full
CanceledYou canceled; the period endedread_only
ExpiredThe grace period ended without paymentblocked, 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:

StatusMeaning
TrialNew workspace on a free trial
ActivePaying customer
SuspendedSet by the platform host. Members cannot sign in to this organization and all its sessions are revoked
ArchivedOffboarded. 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

VariablePurposeDefault
DATABASE_URLPostgreSQL connection stringpostgres://zentro:zentro@localhost:5432/zentro
ZENTRO_ISSUERPublic URL of the API, used as the token iss. HTTPS turns on Secure cookieshttp://localhost:8000
ZENTRO_FRONTEND_URLPublic URL of the portal (login, consent, invites)http://localhost:3000
CORS_ALLOWED_ORIGINSComma-separated origins allowed to call the API with credentialsthe frontend URL
ZENTRO_ENCRYPTION_KEY32 random bytes (base64) that encrypt MFA and webhook secrets at restgenerated into storage/keys/app.key
ZENTRO_ACCESS_TTLAccess token lifetime in seconds900
ZENTRO_REFRESH_TTLRefresh token lifetime in seconds2592000
ZENTRO_INVITE_TTL_HOURSInvitation expiry48
ZENTRO_GRACE_DAYSGrace period after a missed payment7
REDIS_URLShared cache for multiple instancesempty (in-memory)
STRIPE_WEBHOOK_SECRET / RAZORPAY_WEBHOOK_SECRETPayment webhook signature secretsempty
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, MAIL_FROMEmail for invitations, OTPs and resets. Empty SMTP_HOST writes mail to storage/logs/mail.logempty

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_app and database zentro on the PostgreSQL that is already installed
  • two systemd services, zentro-api and zentro-web, listening on free ports on 127.0.0.1 only
  • one nginx site for your domain (checked with nginx -t before reload) and, if you set LETSENCRYPT_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:

SecretValue
DEPLOY_HOSTServer IP or host name
DEPLOY_USERSSH user with sudo
DEPLOY_SSH_KEYPrivate key of a deploy key whose public key is in the user's ~/.ssh/authorized_keys (recommended)
DEPLOY_PASSWORDInstead of a key: the SSH password (also used for sudo)
LETSENCRYPT_EMAILOptional. 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_id set.
  • HTTPS (TLS 1.2+) in front of both apps. Refresh cookies are HttpOnly, SameSite=Lax, and Secure when 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 run npm run sweep and npm run rotate-keys from cron.
  • Several API instances need the same ZENTRO_KEYS_PATH directory, the same ZENTRO_ENCRYPTION_KEY, and REDIS_URL.
  • Daily database backups with point-in-time recovery, plus a copy of the signing keys and encryption key.
  • NODE_ENV=production and ZENTRO_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:action per 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)#

  1. Create the subscription in your gateway and put the Zentro organization id in its metadata (metadata.organization_id for Stripe, notes.organization_id for Razorpay).
  2. Point the gateway webhook to:
    • Stripe: POST {ZENTRO_ISSUER}/api/v1/webhooks/stripe (events invoice.paid, invoice.payment_failed, customer.subscription.deleted)
    • Razorpay: POST {ZENTRO_ISSUER}/api/v1/webhooks/razorpay (events subscription.charged, subscription.halted, payment.failed, subscription.cancelled)
  3. Set STRIPE_WEBHOOK_SECRET or RAZORPAY_WEBHOOK_SECRET.

Zentro verifies the signature, records the invoice (idempotently), moves the subscription to Active, Past due or Canceled, and notifies connected apps.


Troubleshooting#

SymptomLikely causeFix
"Token is not scoped to this organization" (403)The token belongs to a different orgSwitch organization, or call the API with that org's token
"All seats are in use" (402)Seat limit reachedAdd a seat pack or upgrade
"Custom roles are available on Growth and above"Plan feature flag custom_roles is offUpgrade, or enable the flag on the plan
App shows "Not in plan"The app key is not in the plan or add-onsAdd the module add-on or change plan
invalid_redirect_uri during SSOThe callback URL is not allow-listedAdd the exact URI to the application
PKCE verification failedcode_verifier does not match the challengeSend the same verifier you hashed
Users get signed out unexpectedlyA refresh token was replayed, so the family was revokedCheck the audit log for auth.refresh_reuse_detected
Invites never arriveSMTP_HOST is empty, so mail goes to storage/logs/mail.logConfigure SMTP, or copy the link from the invite dialog
Members of a tenant cannot sign inOrganization is suspended or archivedPlatform admin → Tenants → set Active

API reference#

Method & pathWho calls itPurpose
GET /.well-known/openid-configurationAppsOIDC discovery
GET /.well-known/jwks.jsonAppsPublic keys for offline JWT checks
GET /oauth/authorizeBrowserStart SSO (Authorization Code + PKCE)
POST /oauth/tokenAppsExchange code, refresh, or client credentials
POST /oauth/revokeAppsRevoke a refresh token family
GET/POST /oauth/logoutBrowser / appsGlobal single logout
POST /api/v1/auth/switch-organizationPortalNew token for another organization
GET /api/v1/userinfoAppsProfile, active organization, role
POST /api/v1/authz/checkAppsLive permission check
GET /api/v1/organizations/{org_id}/entitlementsAppsPlan, apps, seats, feature flags
GET /api/v1/organizations/{org_id}/membersApps / portalList members
POST /api/v1/organizations/{org_id}/membersPortalInvite a member