Super Admin Guide¶

Managing your AuthVital instance as a super administrator.

Overview¶

Super Admins have full control over the AuthVital instance:

• Manage applications and OAuth clients
• Configure instance-wide settings
• Create and manage tenants
• View all users across tenants
• Configure SSO providers
• Manage system webhooks
• Create other super admins

First Login¶

Initial Setup¶

When AuthVital starts with SUPER_ADMIN_EMAIL configured:

1. A super admin account is created automatically
2. A password reset email is sent (or logged to console in dev)
3. Navigate to https://your-authvital.com/admin
4. Click "Reset Password" and check your email
5. Set a strong password
6. Enable MFA immediately

Accessing Admin Panel¶

https://your-authvital.com/admin

Login with your super admin credentials. If MFA is required, you'll be prompted for a TOTP code.

Dashboard¶

The admin dashboard shows:

• Instance Stats: Total users, tenants, applications
• Recent Activity: Latest signups, logins, events
• System Health: Database status, API health

Managing Applications¶

Creating an Application¶

1. Go to Applications → Create New
2. Configure:

1. Save to generate client_id (and client_secret for MACHINE type)

Application Settings¶

Disabling an Application¶

Disabling an application prevents all new logins and revokes active sessions, but preserves all configuration and data.

1. Go to Applications → select the application
2. Scroll to the Danger Zone at the bottom
3. Click Disable Application
4. Confirm in the modal

What happens when you disable:

To re-enable, click Enable Application in the same Danger Zone section.

Deleting an Application¶

⚠️ This action is irreversible. Deleting an application permanently removes it and all associated data.

Prerequisites: - The application must be disabled first (the Delete button is locked while active)

Steps: 1. Disable the application first (see above) 2. In the Danger Zone, click Delete Application 3. Type the application name to confirm 4. Click Delete Application

What gets deleted:

A application.deleted webhook event is dispatched to all configured system webhooks before final deletion.

Licensing Modes¶

Creating License Types¶

1. Go to Application → Licenses tab
2. Click Add License Type
3. Configure:

{
  name: "Pro Plan",
  slug: "pro",
  description: "For growing teams",
  features: {
    "api-access": true,
    "advanced-reports": true,
    "sso": false,
    "audit-logs": false,
  },
  displayOrder: 2,
}

Managing Tenants¶

Viewing Tenants¶

Tenants page shows all organizations:

• Name and slug
• Member count
• Created date
• Status

Creating a Tenant¶

1. Go to Tenants → Create New
2. Fill in:
3. Name: "Acme Corporation"
4. Slug: acme-corp (auto-generated if blank)
5. Optionally assign initial owner

Tenant Details¶

Click a tenant to see:

Managing Members¶

From tenant details → Members:

• Invite: Send invitation to email
• Change Role: Owner, Admin, or Member
• Suspend: Temporarily disable access
• Remove: Remove from tenant

Managing Users¶

User List¶

Users page shows all users across tenants:

• Email and name
• Email verification status
• MFA status
• Tenant memberships

User Details¶

Click a user to see:

• Profile information
• Tenant memberships
• Active sessions
• License assignments
• SSO links

Admin Actions¶

Instance Settings¶

General Settings¶

Branding¶

Configure default branding for login pages:

• Logo and icon URLs
• Primary and accent colors
• Background color/gradient
• Support, privacy, terms links

Security Settings¶

SSO Configuration¶

Instance-Level SSO¶

Configure SSO providers available to all tenants:

1. Go to Settings → SSO
2. Select provider (Google or Microsoft)
3. Enter OAuth credentials
4. Configure options:

Testing SSO¶

After configuration: 1. Log out of admin panel 2. Go to regular login page 3. Click "Sign in with Google/Microsoft" 4. Verify the flow works

API Keys¶

Instance API Keys¶

Create API keys for programmatic instance access:

1. Go to Settings → API Keys
2. Click Create Key
3. Name it (e.g., "CI/CD Pipeline")
4. Set permissions and expiration
5. Copy the key immediately (shown only once!)

Key Permissions¶

System Webhooks¶

Configure webhooks for system-wide events:

1. Go to Settings → Webhooks
2. Click Add Webhook
3. Configure:

Available Events¶

• subject.* - User lifecycle
• member.* - Membership changes
• invite.* - Invitation events
• license.* - License assignments
• app_access.* - App access changes

Managing Super Admins¶

Creating Another Super Admin¶

1. Go to Settings → Accounts
2. Click Add Super Admin
3. Enter email address
4. New admin receives password reset email

Super Admin Permissions¶

All super admins have equal permissions. There's no hierarchy - any super admin can:

• Create/delete other super admins
• Modify all settings
• Access all data

Removing a Super Admin¶

1. Go to Settings → Accounts
2. Find the admin
3. Click Deactivate or Delete

⚠️ Cannot delete the last super admin!

Audit Logs¶

Super admin actions are logged:

• Login/logout events
• Configuration changes
• User management actions
• Tenant modifications

View at Settings → Audit Log

Security Best Practices¶

✅ Do¶

1. Enable MFA - All super admins should use MFA
2. Use strong passwords - 16+ characters, unique
3. Limit super admins - Only those who need it
4. Review access regularly - Audit who has admin access
5. Use API keys carefully - Set expiration, minimum permissions

❌ Don't¶

1. Don't share credentials - Each admin gets own account
2. Don't skip MFA - Even for "just testing"
3. Don't use production admin for dev - Separate environments
4. Don't leave sessions open - Log out when done

Troubleshooting¶

Emergency Recovery¶

If you're locked out of your super admin account, use these recovery options in order:

1. Ask another super admin to reset your password or disable your MFA
2. Use the CLI recovery tool (recommended for self-recovery)

CLI Recovery Tool (Recommended)¶

AuthVital includes a secure CLI tool for emergency admin recovery. This is the preferred method when another super admin isn't available.

Reset Password¶

Generate a new temporary password:

pnpm recover-admin reset-password --email admin@example.com

This will: - Generate a secure temporary password - Set must_change_password = true (forces password change on next login) - Log the action to the audit trail - Display the temporary password in the terminal

Disable MFA¶

Remove MFA from a locked-out account:

pnpm recover-admin disable-mfa --email admin@example.com

This will: - Disable MFA on the account - Clear the MFA secret and backup codes - Log the action to the audit trail

Unlock Account¶

Unlock an account that's been locked due to failed login attempts:

pnpm recover-admin unlock-account --email admin@example.com

This will: - Reset the failed login counter - Clear any account lockout - Log the action to the audit trail

CLI Options¶

Example with reason:

pnpm recover-admin reset-password --email admin@example.com --reason "Lost phone with MFA app"

Direct Database Access¶

Related Documentation¶

• Application Setup
• Security Best Practices
• Configuration Reference