Client Onboarding & Integration Guide

Verge Auth enables client applications such as HRMS, ERP, Payroll systems, Admin dashboards, and SaaS platforms to operate as secure, centrally governed services.

Client applications do not implement authentication, role-based access control, or token validation. All identity, authorization, and permission enforcement is centrally handled by Verge Auth.

🧠 Architecture Overview

Verge Auth follows a centralized identity, decentralized business logic architecture. Your application focuses purely on domain logic, while Verge Auth enforces security boundaries.

System Responsibilities

Component	Responsibility
Verge Auth Platform	Identity, login, organizations, tenants, users, roles, groups, permissions
Client Application	Business logic (employees, payroll, attendance, leaves, domain data)
Verge Auth SDK	Authentication & authorization enforcement layer

Once integrated, the client application becomes a protected service governed by Verge Auth.

🏢 Organization & Tenant Model

Verge Auth is designed for multi-tenant SaaS architectures with strict isolation guarantees.

Organization

Top-level customer account
Owns users, tenants, and integrated services

Tenant (Optional)

Sub-workspace within an organization
Independent users and permissions
Fully isolated from other tenants

Request Scope

platform — Organization-level access
tenant — Tenant-level access

Scope is cryptographically enforced on every request.

🔁 End-to-End Request Flow

User
↓
Verge Auth Hosted Login
↓
Client Frontend (HRMS / ERP UI)
↓
Client Backend (FastAPI)
↓
Verge Auth SDK Middleware
↓
Authorized Business Route

All authentication and authorization checks are completed before any business logic executes.

🔌 SDK Integration

Install the SDK

pip install verge_auth_sdk

Attach SDK to Your Application

from fastapi import FastAPI
from verge_auth_sdk import add_central_auth

app = FastAPI()

@app.get("/employees")
def list_employees():
    return []

# IMPORTANT: Must be the last line
add_central_auth(app)

❌ No decorators
❌ No JWT parsing
❌ No permission logic in code

Authorization is enforced automatically by the Verge Auth SDK.

🧭 Automatic Route & Permission Sync

All API routes are auto-discovered
Routes sync instantly with Verge Auth
CRUD permissions are inferred from HTTP methods

Route	Method	Permission
/employees	GET	Read
/employees	POST	Create
/employees/{id}	PUT	Update
/employees/{id}	DELETE	Delete

🎛 Role-Based Access Control (RBAC)

Creating Roles

Go to Roles → New Role
Enter role name (e.g. HR, EMPLOYEE)
Select the service
Assign route-level permissions or full access
Save

Assigning Roles

Assign roles directly to users
Assign roles to groups (recommended)

👤 Accessing Verified Auth Context

The Verge Auth SDK injects a cryptographically verified auth context into each authorized request.

from fastapi import Request

@app.get("/employees/me")
def me(request: Request):
    auth = request.state.auth
    return {
        "auth_user_id": auth["user_id"],
        "organization_id": auth["organization_id"],
        "tenant_id": auth.get("tenant_id"),
        "scope": auth["scope"],
        "roles": auth["roles"],
    }

This context must be used for data ownership, filtering, and isolation.

🗄 Data Ownership & Isolation

Verge Auth Owns

Users & credentials
Organizations & tenants
Roles, groups, permissions
Sessions & tokens

Client Application Owns

Employees
Payroll
Attendance
Domain-specific business data

Identity Linking

employees
---------
id
auth_user_id
organization_id
tenant_id
first_name
department
salary

❌ What Client Applications Must NOT Do

Implement authentication
Store passwords
Validate JWTs manually
Hardcode role logic
Trust frontend org or tenant input

🛡 Security Guarantees

Asymmetric JWT verification with key rotation
Centralized session lifecycle
Encrypted service credentials
Multi-layer permission enforcement
HTTPS-only communication

💼 Ideal Use Cases

HRMS & ERP platforms
Payroll systems
Admin dashboards
Multi-tenant SaaS products

✅ Summary

With Verge Auth SDK, client applications become secure, governed services.

Identity & access fully centralized
RBAC managed visually
Permission changes apply instantly
No authentication logic in client apps

You focus on business logic.
Verge Auth handles identity, access, and security.

🆘 Support & Onboarding

Our team provides hands-on onboarding and integration support to help you go live quickly and securely with Verge Auth.

🌐 Website: https://www.vergeinfosoft.com
📧 Email: contactus@vergeinfosoft.com

Building custom software, SaaS platforms, and digital solutions for growing brands