Managing Permissions

Master AuthTuna's permission system — the atomic building blocks of your authorization model

The Foundation of Access Control

Permissions are the granular capabilities that define what actions users can perform in your system. They are the atomic units of authorization, representing specific operations like "create a post", "delete a user", or "view analytics". Unlike roles, permissions are never assigned directly to users — they are always bundled into roles for better management.

Granular Control

Define specific actions users can perform, enabling precise access control down to individual operations.

Role Composition

Permissions are combined into roles, making it easy to manage complex authorization logic through composition.

Audit Ready

Every permission check is logged, providing complete audit trails for security and compliance.

Creating Permissions

Creating permissions involves defining their name and description. AuthTuna validates permissions to prevent duplicates and ensures proper naming conventions.

Permission Properties

namestring (required)

descriptionstring (optional)

Creating a Permission

from authtuna.integrations import auth_service

permission_manager = auth_service.permissions

# Create a new permission
new_permission = await permission_manager.create(
    name="posts:create",
    description="Allows users to create new blog posts"
)

# Or use get_or_create for idempotent operations
permission, created = await permission_manager.get_or_create(
    name="posts:publish",
    defaults={"description": "Allows publishing posts to make them public"}
)

if created:
    print("Permission was created")
else:
    print("Permission already exists")

✅ What Happens

• Permission name is validated for uniqueness
• Database record is created with audit trail
• Permission becomes available for role assignment
• Transaction is committed atomically

❌ Common Mistakes

• Creating duplicate permissions
• Using inconsistent naming patterns
• Forgetting descriptive names
• Not handling creation failures

Permission Naming Conventions

Well-structured permission names make your authorization system maintainable and understandable. AuthTuna follows a hierarchical naming pattern that's both readable and scalable.

The Pattern: resource:action

Use colon-separated hierarchies to organize permissions by resource and action. This creates a natural taxonomy that's easy to understand and query.

Examples:
• posts:create - Create blog posts
• users:manage - Manage user accounts
• reports:view - View analytics reports
• org:teams:invite - Invite members to organization teams

✅ Good Practices

Use lowercase: posts:create not Posts:Create
Be specific: posts:publish not posts:edit
Use hierarchies: org:teams:manage for nested resources
Be consistent: Follow patterns across your application
Use verbs: create, read, update, delete, manage, view, etc.

❌ Anti-Patterns

Too generic: admin - what does it allow?
Mixed case: Posts:Create - inconsistent
Too specific: posts:create:with:image - over-complicated
UI-focused: show:admin:panel - describes interface, not capability

Real-World Examples

Blog Platform

• posts:create
• posts:edit
• posts:publish
• comments:moderate

E-commerce

• products:manage
• orders:view
• inventory:update
• customers:support

Permission Validation & Security

AuthTuna includes comprehensive validation and security measures to ensure your permission system remains robust and secure.

Uniqueness Validation

Permission names must be unique across your entire system. AuthTuna prevents duplicate permissions to avoid confusion and security issues.

# This will raise ValueError if permission already exists
try:
    permission = await permission_manager.create("posts:create", "Create posts")
except ValueError as e:
    print(f"Permission creation failed: {e}")

# Use get_or_create for safe operations
permission, created = await permission_manager.get_or_create("posts:create")
if not created:
    print("Permission already exists - no action needed")

Audit Trail

Every permission creation is logged with timestamps and user information for complete audit trails.

# Permission creation automatically logs:
# - Who created the permission
# - When it was created
# - Permission name and description
# - Any errors or validation failures

# View audit logs
audit_logs = await db_manager.get_audit_logs(
    action="PERMISSION_CREATED",
    limit=50
)

Input Sanitization

Permission names are validated and sanitized to prevent injection attacks and ensure system stability.

# AuthTuna validates permission names:
# - No special characters that could cause issues
# - Reasonable length limits
# - Proper formatting (lowercase, colons, hyphen, underscore allowed)
# - No SQL injection vectors

Permission Lifecycle

Understanding how permissions flow through your system helps you design better authorization logic.

The Permission Flow

Creation

Permissions are created with names and descriptions

Assignment to Roles

Permissions are bundled into roles for user assignment

Role Assignment to Users

Users receive permissions through role assignments

Permission Checks

Application code checks user permissions for operations

Querying Permissions

# Get a permission by name
permission = await permission_manager.get_by_name("posts:create")

# Check if permission exists
if permission:
    print(f"Found: {permission.name} - {permission.description}")
else:
    print("Permission not found")

# Get or create pattern
perm, created = await permission_manager.get_or_create(
    "analytics:view",
    defaults={"description": "View analytics dashboard"}
)

Integration with Roles

# Permissions are assigned to roles, not users
await role_manager.add_permission_to_role(
    role_name="ContentEditor",
    permission_name="posts:create",
    adder_id=current_user.id
)

# Users get permissions through roles
await role_manager.assign_to_user(
    user_id="user_123",
    role_name="ContentEditor",
    assigner_id=admin_user.id
)

# Now user_123 has posts:create permission

Best Practices & Security

✅ Design Principles

• Use principle of least privilege
• Keep permissions granular but not microscopic
• Document permission purposes clearly
• Plan permission hierarchies upfront
• Use consistent naming across your app

🔧 Implementation Tips

• Create permissions during app startup
• Use get_or_create for safe initialization
• Validate permissions before use
• Log permission-related operations
• Test permission checks thoroughly

❌ Common Pitfalls

• Creating too many fine-grained permissions
• Assigning permissions directly to users
• Using inconsistent naming patterns
• Forgetting to handle permission failures
• Not auditing permission changes

🛡️ Security Considerations

• Regularly review permission assignments
• Monitor for privilege escalation attempts
• Use scopes to limit permission scope
• Implement permission expiration where needed
• Audit all permission management operations

Key Takeaways

Permissions are Atomic: They represent the smallest units of authorization in your system
Always Use Roles: Never assign permissions directly to users — bundle them into roles
Consistent Naming: Use hierarchical patterns like resource:action for clarity
Validate Everything: AuthTuna prevents duplicates and validates inputs for security
Audit Everything: Every permission operation is logged for compliance and debugging