Developer Documentation

Enterprise Access Governance Platform

Build secure applications with centralized identity, RBAC, and audit intelligence.

⚡ Quick Start

Get running in 5 minutes with the Verge Auth SDK.

1. Install the SDK

▼

pip install verge-auth-sdk

npm install @verge-auth/sdk

npm install @vergeinfosoft/react

2. Initialize in Your App

▼

from fastapi import FastAPI
from verge_auth_sdk import add_central_auth

app = FastAPI()

# Your routes here
@app.get("/api/users")
def get_users():
    return {"users": []}

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

3. Configure Environment

▼

Backend Environment Variables (.env)

# Core
DATABASE_URL=postgresql://:@:5432/
SERVICE_BASE_URL=http://localhost
SERVICE_FRONTEND_URL=http://localhost:5175
ENABLE_AUDIT_LOGGING=true
ENVIRONMENT=development

# Verge Auth
AUTH_FRONTEND_URL=https://app.vergeauth.in
AUTH_BASE_URL=https://api.vergeauth.in
SERVICE_NAME=your-service-name
VERGE_CLIENT_ID=your_client_id_here
VERGE_CLIENT_SECRET=your_client_secret_here
VERGE_SERVICE_SECRET=your_service_secret_here
PUBLIC_PATHS=["/health","/docs","/openapi.json","/favicon.ico"]

Frontend Environment Variables (.env)

VITE_API_BASE_URL=/api
VITE_VERGEAUTH_LOGIN_URL=https://app.vergeauth.in/login
VITE_APP_BASE_URL=http://localhost:5175

4. Start Your App

▼

uvicorn main:app --reload

Your service is now protected by Verge Auth. Visit your dashboard to configure roles and permissions.

⚛️ React SDK Integration Guide

Comprehensive step-by-step guide to integrate Verge Auth into your React application using the official React SDK.

Prerequisites: React application (Vite), FastAPI backend, Verge Auth credentials (CLIENT_ID, CLIENT_SECRET, SERVICE_SECRET), Docker (optional for containerized deployment).

Step 1: Frontend Integration (React SDK)

1.1 Install the React SDK

Add the Verge Auth React SDK to your package.json:

{
  "dependencies": {
    "@vergeinfosoft/react": "^1.0.0"
  }
}

Then install:

npm install

1.2 Configure Environment Variables

Create or update .env file in your frontend:

# Verge Auth Configuration
VITE_API_BASE_URL=/api
VITE_VERGEAUTH_LOGIN_URL=https://app.vergeauth.in/login
VITE_APP_BASE_URL=http://localhost:5175

Frontend .env.production (for CI/CD builds):

VITE_API_BASE_URL=/api
VITE_VERGEAUTH_LOGIN_URL=https://app.vergeauth.in/login
VITE_APP_BASE_URL=https://app.vergehrm.com

1.3 Wrap App with VergeAuth

Update src/main.jsx:

import React from "react";
import ReactDOM from "react-dom/client";
import { VergeAuth } from "@vergeinfosoft/react";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")).render(
  
    
  
);

1.4 Protect Routes with ProtectedRoute

Update src/App.jsx (no BrowserRouter needed – VergeAuth provides it):

import React from "react";
import { Routes, Route, Navigate } from "react-router-dom";
import { ProtectedRoute } from "@vergeinfosoft/react";
import Dashboard from "./pages/Dashboard";

export default function App() {
  return (
    
      
        } />
        
            
          
        } />
      
    
  );
}

1.5 Use Auth Context in Components

import { useAuth } from "@vergeinfosoft/react";

function Dashboard() {
  const { isAuthenticated, loading, user, permissions, logout } = useAuth();

  if (loading) return Loading...;
  if (!isAuthenticated) return null;

  return (
    
      Welcome, {user?.name}
      
    
  );
}

Step 2: Backend Integration (Python SDK)

2.1 Install the Python SDK

Add to requirements.txt:

verge_auth_sdk==0.1.109

Install:

pip install -r requirements.txt

2.2 Configure Environment Variables

Create or update .env file in your backend:

# Core
DATABASE_URL=postgresql://:@:5432/
SERVICE_BASE_URL=http://localhost
SERVICE_FRONTEND_URL=http://localhost:5175
ENABLE_AUDIT_LOGGING=true
ENVIRONMENT=development

# Verge Auth
AUTH_BASE_URL=https://api.vergeauth.in
AUTH_FRONTEND_URL=https://app.vergeauth.in
SERVICE_NAME=your-service-name

# Your Verge Auth Credentials (from dashboard)
VERGE_CLIENT_ID=your_client_id_here
VERGE_CLIENT_SECRET=your_client_secret_here
VERGE_SERVICE_SECRET=your_service_secret_here

# Public routes
PUBLIC_PATHS=["/health","/docs","/openapi.json","/favicon.ico"]

2.3 Integrate SDK in FastAPI App

Update app/main.py:

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from verge_auth_sdk import add_central_auth
from .routes import router

app = FastAPI(title="Your Service")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.yourdomain.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(router)

# MUST be the last line in main.py
add_central_auth(app)

2.4 Access Authenticated User in Routes

from fastapi import Request

@router.get("/dashboard")
def dashboard_bootstrap(request: Request):
    user = request.state.user
    
    return {
        "dashboard": "ok",
        "user": user
    }

Step 3: Nginx Configuration (Logout Endpoint)

Update your Nginx configuration:

server {
    listen 80;
    server_name localhost;

    # Clear auth cookies on logout
    location /auth/logout {
        add_header Set-Cookie "verge_auth=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT; HttpOnly; SameSite=Lax";
        add_header Set-Cookie "verge_auth_refresh=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT; HttpOnly; SameSite=Lax";
        return 302 $VITE_VERGEAUTH_LOGIN_URL;
    }

    # Proxy API to backend
    location /api/ {
        proxy_pass http://backend-service:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Serve frontend
    location / {
        proxy_pass http://frontend-ui:5175;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Step 4: Docker Compose Configuration

services:
  backend-service:
    build: ./backend
    container_name: backend-service
    env_file:
      - ./backend/.env
    ports:
      - "8000:8000"
    depends_on:
      - database
    networks:
      - app-net
    restart: on-failure

  frontend-ui:
    build: ./frontend
    container_name: frontend-ui
    ports:
      - "5175:5175"
    depends_on:
      - backend-service
    networks:
      - app-net
    restart: unless-stopped

  reverse-proxy:
    image: nginx:alpine
    container_name: reverse-proxy
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - backend-service
      - frontend-ui
    networks:
      - app-net
    restart: unless-stopped

networks:
  app-net:
    driver: bridge

Step 5: Testing

5.1 Start Services

docker-compose up --build

5.2 Test Flow

Navigate to http://localhost:5175
You should be redirected to Verge Auth login page
Login with your Verge Auth credentials
You should be redirected back to your app at /dashboard

5.3 Test Logout

Click the logout button. You should be redirected to the login page and cookies cleared.

Troubleshooting

Issue: 403 on `/auth/me`

Cause: This is expected behavior. 403 means the user is authenticated but missing route permission.

Solution: The SDK treats 403 as authenticated. No action needed.

Note: /api/auth/me should be in PUBLIC_PATHS OR grant the appropriate permission to every role in the Verge Auth dashboard. The SDK’s permission check runs on every authenticated request, so ensure roles have this permission.

Issue: Redirect loop

Cause: SERVICE_NAME doesn’t match dashboard configuration.

Solution: Ensure SERVICE_NAME in backend .env exactly matches the service name in Verge Auth dashboard.

Issue: Logout not working

Cause: JavaScript trying to clear httpOnly cookies.

Solution: Ensure Nginx /auth/logout endpoint is configured to clear cookies.

Integration effort: Frontend (3 file changes), Backend (2 file changes + .env), Nginx (1 location block). Total time: ~15 minutes.

🔐 Authentication Flow

Understanding how authentication works in Verge Auth.

1. User authenticates with Verge Auth

↓

2. Secure session established

↓

3. Application receives authenticated context

↓

4. Protected routes become accessible

Secure Authentication Lifecycle

Verge Auth uses industry-standard OAuth 2.0 protocols for secure authentication:

Step 1: User is redirected to Verge Auth login page
Step 2: User authenticates and grants consent
Step 3: Verge Auth establishes a secure session
Step 4: Application receives authenticated user context
Step 5: Protected routes become accessible to the user

🧭 Intelligent Permission Discovery

Your code defines your permissions automatically. This is Verge Auth’s most powerful feature—no manual configuration required.

Zero manual permission configuration. Write your routes, and Verge Auth automatically creates permissions. Routes become permissions instantly.

How It Works

Verge Auth automatically detects your protected application endpoints and transforms them into assignable permissions:

Deploy your application with Verge Auth SDK integrated
Verge Auth discovers your routes automatically through the SDK
Permissions are created instantly based on your route structure
Assign permissions to roles in the dashboard with one click

Why This Matters

No boilerplate: Don’t write permission definitions. Your code is the definition.
Always in sync: Add a route → permission appears automatically. Delete a route → permission disappears.
Faster development: Focus on features, not permission configuration.
Less error-prone: No mismatch between code and permissions.

Permission Structure

Your routes automatically become permissions:

Your Route	Method	Auto-Generated Permission
/api/users	GET	users:read
/api/users	POST	users:create
/api/users/{id}	PUT	users:update
/api/users/{id}	DELETE	users:delete

This is the feature developers remember. No other platform makes permission management this automatic. Your code is your permission definition.

🎨 App Branding

Display your application’s brand name on the Verge Auth login screen for a seamless branded experience.

How It Works

Verge Auth automatically detects your application by its domain and displays the configured brand name on the login screen. When users are redirected from your application (e.g., https://app.yourdomain.com), Verge Auth matches the domain to your registered service and shows your custom brand name.

Configuring Your Brand Name

Set your brand name when generating secrets for your application:

Log in to your Verge Auth dashboard
Navigate to Applications
Click Generate Secrets
Enter a Secrets Name to identify your credentials
Enter your App Brand Name (e.g., “Verge HRM”, “MyApp”)
Click Generate

What Users See

When users access your application, they will see:

Your App Brand Name – prominently displayed on the login screen
“Powered by Verge Auth” – subtle attribution below your brand name

Zero configuration needed in your application code. The branding is automatically applied based on your domain and dashboard configuration. No app_name parameters or API calls required.

🎛 RBAC APIs

Programmatically manage roles, permissions, and access control. Note: All APIs require authentication and appropriate permissions.

Required Roles: PLATFORM_OWNER, SUPER_ADMIN (org/tenant), or users with permissions.assign permission.

Create Role

▼

Use Case: Define custom roles for your organization (e.g., “HR Manager”, “Finance Admin”, “Developer”) when default roles don’t meet your needs.

POST /roles
{
  "name": "HR Manager",
  "description": "Full access to HR module"
}

Assign Permissions to Role

▼

Use Case: Grant specific permissions to roles to control what each role can do. Example: Give “HR Manager” access to employee management but not billing.

POST /permissions/assign/{role_id}
{
  "permission_ids": [1, 2, 3, 4]
}

Assign Role to User

▼

Use Case: Automate user onboarding by assigning appropriate roles based on job function. Example: New employee joins → assign “Developer” role.

POST /users/{user_id}/roles
{
  "role_name": "HR Manager"
}

List Permissions

▼

Use Case: View all available permissions in the system or see what permissions a specific role currently has. Used for configuring roles in dashboards or debugging access issues.

GET /permissions?role_id={role_id}

Response:
[
  {
    "id": 1,
    "key": "users:read",
    "name": "Read Users"
  },
  {
    "id": 2,
    "key": "users:create",
    "name": "Create Users"
  }
]

🔑 Enterprise Token Security

Verge Auth securely validates authentication context, session integrity, and application authorization using industry-standard protocols and rotating cryptographic keys.

Security Standards

Verge Auth uses industry-standard security protocols:

OAuth 2.0 & OIDC: Standard authentication protocols
SAML 2.0: Enterprise single sign-on support
JWKS: Public key verification with automatic key rotation
Asymmetric Cryptography: Secure token validation

Never validate tokens manually. The SDK handles all validation automatically using industry-standard protocols.

🔔 Webhooks & Events Planned Feature

Receive real-time notifications about authentication and authorization events.

This feature is planned for future releases. Contact us if you’re interested in webhooks integration.

Planned Events

user.created – New user registered
user.login – User logged in
user.logout – User logged out
role.assigned – Role assigned to user
permission.denied – Access denied event
route.synced – Routes synced to platform

Use Cases

Real-time audit logging and compliance
Integration with external systems (CRM, SIEM, monitoring tools)
Automated workflows based on auth events
Multi-system synchronization

🆘 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

Developer Documentation

⚡ Quick Start

1. Install the SDK

2. Initialize in Your App

3. Configure Environment

4. Start Your App

⚛️ React SDK Integration Guide

Step 1: Frontend Integration (React SDK)

1.1 Install the React SDK

1.2 Configure Environment Variables

1.3 Wrap App with VergeAuth

1.4 Protect Routes with ProtectedRoute

1.5 Use Auth Context in Components

Welcome, {user?.name}

Step 2: Backend Integration (Python SDK)

2.1 Install the Python SDK

2.2 Configure Environment Variables

2.3 Integrate SDK in FastAPI App

2.4 Access Authenticated User in Routes

Step 3: Nginx Configuration (Logout Endpoint)

Step 4: Docker Compose Configuration

Step 5: Testing

5.1 Start Services

5.2 Test Flow

5.3 Test Logout

Troubleshooting

Issue: 403 on /auth/me

Issue: Redirect loop

Issue: Logout not working

🔐 Authentication Flow

Secure Authentication Lifecycle

🧭 Intelligent Permission Discovery

How It Works

Why This Matters

Permission Structure

🎨 App Branding

How It Works

Configuring Your Brand Name

What Users See

🎛 RBAC APIs

Create Role

Assign Permissions to Role

Assign Role to User

List Permissions

🔑 Enterprise Token Security

Security Standards

🔔 Webhooks & Events Planned Feature

Planned Events

Use Cases

🆘 Support & Onboarding

Next Steps

Issue: 403 on `/auth/me`