PADAI Enterprise — Admin Setup Guide

This is the handbook for the IT administrator who purchased a PADAI Enterprise or Enterprise+ subscription and is now responsible for:

1. Deploying the pad_server Docker image on-premise
2. Wiring Microsoft Entra ID (Azure AD) SSO
3. Provisioning users (seats) and, optionally, the central OpenAI key for voice transcription
4. Ongoing administration (user lifecycle, audit, upgrades)

Not for end users — regular employees receive a separate "Getting started" email with the download link and their login instructions. This guide is only delivered to the Enterprise Admin email on file.

---

1. What you received after purchase

Within ~5 minutes of the Stripe checkout completing, the Admin Email on file receives two messages from noreply@contact.padai.tech:

Email	Subject	Contains
Welcome	Welcome to PADAI Enterprise — setup guide attached	Link to this guide + your enterprise_tenant_id + the Enterprise admin JWT (30-day, renewable)
Billing	Your PADAI Enterprise invoice	Stripe receipt, subscription ID, link to Stripe customer portal

If either is missing, contact sales@padai.tech with your organisation name and purchase date.

What's in the admin JWT

The admin JWT lets you call the /admin/enterprise/* endpoints on licensing.padai.tech. Decoded payload:

{
  "tier": "enterprise",
  "is_enterprise_admin": true,
  "enterprise_tenant_id": 42,
  "seat_quota": 25,
  "exp": 1735689600
}

Keep the JWT in a password manager — it's the key to the admin console at https://licensing.padai.tech/enterprise-admin#<jwt>.

---

2. Deploy pad_server on your infrastructure

PADAI Enterprise ships pad_server as a Docker image. Minimum specs:

Component	Minimum	Recommended
vCPU	2	4
RAM	4 GB	8 GB
Disk	10 GB	50 GB (for run-log retention)
Network	HTTPS ingress from employee LAN	Behind corporate reverse-proxy
Database	SQLite (bundled)	Postgres 14+ (recommended > 10 users)

2.1 Pull the image

# Use the image URL sent in your welcome email
docker pull registry.padai.tech/pad-server:enterprise-1.0

The image is signed with cosign; verify with:

cosign verify --key https://padai.tech/cosign.pub \
    registry.padai.tech/pad-server:enterprise-1.0

2.2 First-run environment

Create /etc/padai/.env with at minimum:

# Licensing (from welcome email)
PADAI_ENTERPRISE_TENANT_ID=42
PADAI_ENTERPRISE_ADMIN_JWT=<paste the JWT here>

# Database
DATABASE_URL=postgresql://padai:<pwd>@db:5432/padai

# Entra ID / Azure AD — see §3 below
AZURE_TENANT_ID=<your Azure tenant UUID>
AZURE_CLIENT_ID=<app registration client ID>
AZURE_CLIENT_SECRET=<app registration secret>

# OpenAI key for voice transcription (optional; see §5)
OPENAI_API_KEY=<your org-level key, or leave empty to disable voice>

# JWT signing (session tokens issued by this server to panels)
SERVER_JWT_SECRET=<generate 64 random bytes, base64>

# Port
PORT=443

2.3 Run

docker run -d \
    --name pad-server \
    --env-file /etc/padai/.env \
    -p 443:443 \
    -v /var/padai/logs:/var/log/padai \
    -v /var/padai/data:/data \
    registry.padai.tech/pad-server:enterprise-1.0

Expose the container on a FQDN your employees' PADAI panels can reach, e.g. padai.example-corp.internal. TLS termination at your reverse proxy (Nginx, Traefik, Azure AppGW, etc.) is the supported pattern — the image itself listens on HTTP inside the container.

2.4 First health check

curl https://padai.example-corp.internal/api/healthz
# → {"status":"ok","version":"1.0","tier":"enterprise"}

---

3. Wire Entra ID (Azure AD) SSO

PADAI Enterprise authenticates employees via Microsoft Entra ID. You register an OIDC application once; each employee then logs in with their work account — no PADAI password.

3.1 Register the app in Azure Portal

1. Go to Azure Portal → Microsoft Entra ID → App registrations → New registration.
2. Name: PADAI Enterprise (visible to users consenting).
3. Supported account types: single tenant.
4. Redirect URI: https://padai.example-corp.internal/auth/callback (match your FQDN).
5. Click Register.

3.2 Grant API permissions

Under API permissions: - User.Read (delegated) — standard profile - email (delegated) - openid, profile (delegated)

Click Grant admin consent for .

3.3 Create client secret

Certificates & secrets → New client secret, 24-month expiry. Copy the Value field (you won't see it again) into AZURE_CLIENT_SECRET in .env.

3.4 Map group claim (optional — needed for is_enterprise_admin)

If you want a specific Entra group to get admin rights in PADAI:

1. Token configuration → Add groups claim → Security groups → ID.
2. Note the group's object ID.
3. In /etc/padai/.env add:

   ENTERPRISE_ADMIN_GROUP_ID=<group-object-id>
   

Members of that group receive is_enterprise_admin=true in their JWT (unlocks billing + seat management in the panel Settings window).

3.5 Test SSO

Have a test user launch PadaiPanel: 1. Onboarding wizard → card "Connexion Microsoft (Enterprise)" 2. Enter https://padai.example-corp.internal as the server URL 3. Browser opens for Entra consent → return to the panel 4. Panel settings should show ENTERPRISE badge + Active license

---

4. Manage users (seats)

The web admin console lives at: https://licensing.padai.tech/enterprise-admin#<your-admin-jwt>

The #jwt fragment is never sent to our server — only JavaScript reads it, then calls /admin/enterprise/* endpoints as a Bearer token.

4.1 What you can do

Action	UI tab	Endpoint
Provision a user (auto on first SSO)	n/a	/admin/enterprise/users (POST, called by Entra callback)
List current users + last-seen	Users	GET /admin/enterprise/users?tenant_id=…
Disable a user (frees seat, stays auditable)	Users → Disable	POST /admin/enterprise/users/{id}/disable
Re-enable a user	Users → Enable	POST /admin/enterprise/users/{id}/enable
Purge (hard-delete for GDPR)	Users → Purge	DELETE /admin/enterprise/users/{id}
Promote / demote admin	Users → Role	POST /admin/enterprise/users/{id}/role
View audit log (last 90 days)	Audit	GET /admin/enterprise/audit
Export users to CSV	Users → Export	GET /admin/enterprise/users/export

4.2 Seat quota enforcement

The seat_quota claim in your admin JWT caps concurrent active users. When the quota is reached the Entra callback returns HTTP 402 and the employee sees a "Seats exhausted — contact your admin" popup in the panel. To raise the quota, upgrade via the Stripe customer portal (link in your billing email).

4.3 Decommissioning an employee

When an employee leaves:

1. Revoke in Entra ID (cuts off future login immediately)
2. Disable the user in /enterprise-admin → frees the seat
3. Optionally Purge after your retention window (GDPR)

Previously-generated PAD code artifacts stay in your flow repo; only the PADAI-side user row is gone.

---

5. Voice transcription key (optional)

If employees use the microphone dictation feature, the panel sends recorded audio to pad_server/api/transcribe, which then forwards to OpenAI Whisper using an API key sourced in this priority order:

1. X-OpenAI-Api-Key header on the request (User / Team flow — user BYO their own key) — blocked on Enterprise by the Entra-gated middleware, because your policy likely is "no employee-provided keys".
2. OPENAI_API_KEY env var on the server — this is the Enterprise path. Configure once in .env, every employee benefits, billing rolls up to your org's OpenAI account.

If OPENAI_API_KEY is not set, employees who click the mic see a popup: "Voice transcription requires your PADAI admin to configure OPENAI_API_KEY on the server." (with your admin contact email, if you set ENTERPRISE_ADMIN_CONTACT_EMAIL in .env).

---

6. Updates

PADAI publishes quarterly Enterprise releases plus critical patches. You control the cadence:

Update method	Downtime
docker pull + docker stop && docker start	~30 s (clients auto-reconnect)
Blue-green behind your reverse proxy	0 s

Subscribe to release-enterprise@contact.padai.tech for notifications. Release notes live at https://docs.padai.tech/enterprise/releases.

Database migrations are automatic on container start. We tag migrations with "safe for rolling upgrade" vs "requires downtime". Check the release notes before pulling if you're bluegreen-deploying.

---

7. Backup & restore

Component	What to back up	Frequency
Postgres	Full pg_dump	Nightly
Logs (/var/log/padai)	Tarball	Weekly (or ship to SIEM)
.env	Vault / password manager	On every change

Restore drill: docker compose down && psql < latest.dump && docker compose up -d && curl /api/healthz. Targets: RTO 15 min, RPO 24 h.

---

8. Security checklist

• [ ] Image verified with cosign
• [ ] SERVER_JWT_SECRET rotated at least yearly
• [ ] .env is not in git; only in your secret store
• [ ] HTTPS-only ingress (no HTTP listener exposed)
• [ ] Azure app registration client secret rotation calendar'd
• [ ] SIEM ingest of /var/log/padai
• [ ] Admin console JWT stored in password manager, not email

---

9. Support

• Product issues, features: support@padai.tech
• Security incidents: security@padai.tech (PGP on https://padai.tech/.well-known/pgp-key.txt)
• Commercial & contract: sales@padai.tech
• Community: https://discord.gg/padai-enterprise (private channel, invite via support@)

SLA for Enterprise: 2-hour response during business hours (EST), 24-hour for weekends. Enterprise+ includes 24/7 pager — credentials sent separately after subscription activation.

---

This guide is shipped automatically with every Enterprise purchase. If you received PADAI via a reseller or VAR, ask them for the current version — or download from docs.padai.tech/enterprise-admin.