Default Provisioning System

Understanding AuthTuna's default users, roles, and permissions — the foundation of your authorization system

What is Default Provisioning?

When AuthTuna starts for the first time, it automatically creates a complete authorization foundation: default permissions, roles with proper hierarchies, and system users. This ensures your application has a working RBAC (Role-Based Access Control) system from day one.

Perfomanze

Provisioning only runs when needed. If system users exist, it skips remaining to avoid waste queries. Controlled by TRY_FULL_INITIALIZE_WHEN_SYSTEM_USER_EXISTS_AGAIN setting.

Production Ready

Designed for real applications with hierarchical roles, scoped permissions, and proper separation between admin and organizational access.

Default Permissions

AuthTuna comes with carefully designed permissions covering administrative access, organization management, and team operations. Each permission includes a clear description of what it allows.

Permission	Description	Category
admin:access:panel	Access the main admin dashboard	Admin
admin:manage:users	Create, edit, suspend, and delete users	Admin
admin:manage:roles	Create roles and manage role assignment grants	Admin
admin:manage:permissions	Create permissions and manage permission grant relationships	Admin
roles:assign:SuperAdmin	Permission to assign the SuperAdmin role	Admin
roles:assign:Admin	Permission to assign the Admin role	Admin
roles:assign:Moderator	Permission to assign the Moderator role	Admin
roles:assign:User	Permission to assign the User role	Admin
org:create	Permission to create a new organization	Organization
org:manage	Permission to edit and delete an organization	Organization
org:invite_member	Permission to invite new members to an organization	Organization
org:remove_member	Permission to remove members from an organization	Organization
team:create	Permission to create a new team within an organization	Team
team:manage	Permission to edit and delete a team	Team
team:invite_member	Permission to invite new members to a team	Team
team:remove_member	Permission to remove members from a team	Team
team:delete	Permission to delete a team	Team

Default Roles & Hierarchy

AuthTuna provides a comprehensive role system with both hierarchical admin roles and flat organization-based roles. Each role has a level (for hierarchical permissions) and comes with pre-assigned permissions.

Administrative Roles (Hierarchical)

SuperAdmin (Level 100)

Highest

Complete system access including user/role management

Permissions: All admin permissions + role assignment powers

Admin (Level 90)

High

Full administrative access to most features

Permissions: User/role management, can assign Moderator/Admin roles

Moderator (Level 50)

Medium

Can manage users and content

Permissions: User management, basic admin access

Organization Roles (Flat)

OrgOwner

Owner

Full control over an organization

Permissions: Manage org, invite/remove members, create/delete teams

OrgAdmin

Admin

Can manage organization's members and teams

Permissions: Invite/remove members, manage teams

TeamLead

Lead

Can manage a specific team and its members

Permissions: Invite/remove team members, manage team

User

Base

Standard user with basic permissions

Permissions: Can create organizations (configurable)

Role Grant System

Higher-level roles can assign lower-level roles. This creates a natural hierarchy:

SuperAdmin → Admin, Moderator, OrgOwner, OrgAdmin, TeamLead, OrgMember, User
Admin → Moderator, OrgOwner, OrgAdmin, TeamLead, OrgMember, User
OrgOwner → OrgAdmin, TeamLead, OrgMember
OrgAdmin → TeamLead, OrgMember
TeamLead → TeamMember

Default System Users

AuthTuna creates three system users by default. The admin users are only created if passwords are configured in settings, providing security by default.

System

[email protected]

Internal system user for automated processes. Has no password and cannot be logged into directly.

Role: System
ID: system

SuperAdmin

{DEFAULT_SUPERADMIN_EMAIL}

Highest privilege user for system administration. It is always created but cannot be logged in unless DEFAULT_SUPERADMIN_PASSWORD is set when the database is first initialized, they cannot be logged in with passwordless login in and after v0.2.1.

Roles: SuperAdmin, User
ID: default-super-admin

Admin

{DEFAULT_ADMIN_EMAIL}

Standard admin user for day-to-day administration. It is always created but cannot be logged in unless DEFAULT_ADMIN_PASSWORD is set when the database is first initialized, they cannot be logged in with passwordless login in and after v0.2.1.

Roles: Admin, User
ID: default-admin

Security Note

By default, admin users are created but not enabled for login unless passwords are set in the configuration. This prevents accidental exposure of admin accounts in development environments. Set DEFAULT_SUPERADMIN_PASSWORD and DEFAULT_ADMIN_PASSWORD in your settings to enable them.

How Provisioning Works

The provisioning process is idempotent and runs automatically when your AuthTuna application starts. Here's what happens behind the scenes:

Check for Existing System

If the system user exists and TRY_FULL_INITIALIZE_WHEN_SYSTEM_USER_EXISTS_AGAIN is False, provisioning is skipped entirely.

Create Permissions

All default permissions are created if they don't exist, ensuring the permission system is complete.

Create Roles

Roles are created with their level, description, and assigned permissions from the role-permission mappings.

Create System Users

System users are created with their predefined roles and credentials (where configured).

Setup Role Grants

Role assignment permissions are configured, allowing higher-level roles to assign lower-level roles.

Provisioning Code Example

from authtuna.core.defaults import provision_defaults
from authtuna.core.database import db_manager

# Run provisioning (typically done automatically on startup)
async with db_manager.get_db() as db:
    await provision_defaults(db)

Customization & Extension

While the defaults provide a solid foundation, you can extend and customize the system to fit your needs.

Adding Custom Permissions

Create application-specific permissions for your domain logic.

# Add custom permissions
custom_permissions = {
    "billing:manage": "Manage billing settings",
    "reports:view": "Access analytics reports",
    "api:webhooks": "Configure webhooks"
}

# Create them in your app startup
for name, desc in custom_permissions.items():
    permission = Permission(name=name, description=desc)
    db.add(permission)

Creating Custom Roles

Define roles specific to your application's needs and assign appropriate permissions.

# Create a custom role
analyst_role = Role(
    name="DataAnalyst",
    level=10,
    description="Can access reports and analytics"
)

# Assign permissions
analyst_permissions = ["reports:view", "billing:manage"]
for perm_name in analyst_permissions:
    permission = get_permission_by_name(perm_name)
    analyst_role.permissions.append(permission)

Key Takeaways

Production Ready: The default system provides enterprise-grade RBAC with proper separation of concerns
Hierarchical & Flat: Combines hierarchical admin roles with flat organization-based roles
Secure by Default: Admin users are disabled unless explicitly configured
Extensible: Easy to add custom permissions and roles for your specific use cases
Safe to run multiple times without conflicts