Roles Reference

AutoCom includes 5 default roles with carefully graduated permission levels. Each role is designed for a specific use case in e-commerce operations.

Role Hierarchy

Owner (68 permissions)
  └── Admin (66 permissions)
        └── Manager (39 permissions)
              └── Agent (14 permissions)
                    └── Viewer (8 permissions)

Owner

Full access to all features. The owner role has complete control over the organization and is automatically assigned to the user who creates the tenant.

Permissions: 68 (all permissions)
Use Case: Business owner, founder
Special: Cannot be assigned via invitation

Exclusive Owner Permissions

settings.manage_billing - Manage billing and subscription
admin.system_settings - Configure system-level settings

Admin

Complete administrative access except billing. Admins can manage all aspects of the business including team management.

Permissions: 66
Use Case: COO, operations director, senior manager

Admin Capabilities

Area	Permissions
Team	Invite, edit, remove members, manage roles
Settings	Store settings, branding, API keys
Integrations	Connect, configure, manage webhooks
All Operations	Full CRUD on orders, products, customers

Permissions Not Included

settings.manage_billing
admin.system_settings

Manager

Operational management with team oversight. Managers can handle day-to-day operations and supervise agents.

Permissions: 39
Use Case: Team lead, shift supervisor, department head

Manager Capabilities

Area	Can Do	Cannot Do
Orders	View, create, edit, export, bulk update	-
Products	View, edit, manage inventory	Create, delete, import
Customers	View, create, edit, export	Delete, merge, view sensitive data
Shipping	All shipping operations	-
Communication	View, send, broadcast, manage templates	-
Team	View team members	Invite, edit, remove
Integrations	View integrations	Connect, configure

Agent

Day-to-day task execution. Agents handle customer interactions and order processing under supervision.

Permissions: 14
Use Case: Customer support, order processor, warehouse staff

Agent Capabilities

Area	Permissions
Dashboard	View dashboard
Orders	View, edit, assign
Customers	View, edit
Products	View
Shipping	View, track, manage NDR
Communication	View, send
Team	View team

Key Limitations

Cannot create or delete orders
Cannot access analytics or reports
Cannot configure integrations
Cannot manage team members

Viewer

Read-only access. Viewers can see data but cannot modify anything.

Permissions: 8
Use Case: Investor, advisor, auditor, stakeholder

Viewer Capabilities

dashboard.view - View main dashboard
orders.view - View order list and details
customers.view - View customer information
products.view - View product catalog
shipping.view - View shipment information
shipping.track - Track shipments
communication.view - View message history
analytics.view_dashboard - View analytics dashboard

Permission Matrix

A complete breakdown of which roles have which permissions:

Dashboard & Analytics

Permission	Owner	Admin	Manager	Agent	Viewer
dashboard.view	✓	✓	✓	✓	✓
dashboard.view_analytics	✓	✓	✓	-	-
analytics.view_dashboard	✓	✓	✓	✓	✓
analytics.view_reports	✓	✓	✓	-	-
analytics.export	✓	✓	✓	-	-
analytics.view_financials	✓	✓	-	-	-
analytics.create_reports	✓	✓	-	-	-

Orders

Permission	Owner	Admin	Manager	Agent	Viewer
orders.view	✓	✓	✓	✓	✓
orders.create	✓	✓	✓	-	-
orders.edit	✓	✓	✓	✓	-
orders.delete	✓	✓	✓	-	-
orders.export	✓	✓	✓	-	-
orders.bulk_update	✓	✓	✓	-	-
orders.assign	✓	✓	✓	✓	-
orders.cancel	✓	✓	✓	-	-
orders.refund	✓	✓	✓	-	-

Customers

Permission	Owner	Admin	Manager	Agent	Viewer
customers.view	✓	✓	✓	✓	✓
customers.create	✓	✓	✓	-	-
customers.edit	✓	✓	✓	✓	-
customers.delete	✓	✓	-	-	-
customers.export	✓	✓	✓	-	-
customers.merge	✓	✓	-	-	-
customers.view_sensitive	✓	✓	-	-	-

Products

Permission	Owner	Admin	Manager	Agent	Viewer
products.view	✓	✓	✓	✓	✓
products.create	✓	✓	-	-	-
products.edit	✓	✓	✓	-	-
products.delete	✓	✓	-	-	-
products.import	✓	✓	-	-	-
products.export	✓	✓	-	-	-
products.manage_inventory	✓	✓	✓	-	-

Team & Settings

Permission	Owner	Admin	Manager	Agent	Viewer
team.view	✓	✓	✓	✓	-
team.invite	✓	✓	-	-	-
team.edit	✓	✓	-	-	-
team.remove	✓	✓	-	-	-
team.manage_roles	✓	✓	-	-	-
settings.view	✓	✓	✓	-	-
settings.edit_store	✓	✓	-	-	-
settings.edit_brand	✓	✓	-	-	-
settings.manage_billing	✓	-	-	-	-
settings.manage_api_keys	✓	✓	-	-	-

Custom Roles

In addition to default roles, you can create custom roles specific to your organization. Custom roles:

Are scoped to a single tenant
Can have any combination of permissions
Cannot override the owner role
Are managed via the Team Management API
Require team.manage_roles permission to create/modify

Creating a Custom Role

POST /api/v1/team/roles
Authorization: Bearer {token}
X-Tenant: my-store
Content-Type: application/json

{
  "name": "Warehouse Manager",
  "description": "Manages inventory and shipping",
  "permissions": [
    "products.view",
    "products.manage_inventory",
    "shipping.view",
    "shipping.create_label",
    "shipping.track"
  ]
}

Response:

{
  "message": "Role created successfully",
  "role": {
    "id": 6,
    "name": "warehouse manager",
    "description": "Manages inventory and shipping",
    "permissions_count": 5
  }
}

Updating a Custom Role

PUT /api/v1/team/roles/{id}
Authorization: Bearer {token}
X-Tenant: my-store
Content-Type: application/json

{
  "name": "Senior Warehouse Manager",
  "description": "Updated description",
  "permissions": [
    "products.view",
    "products.create",
    "products.edit",
    "products.manage_inventory",
    "shipping.view",
    "shipping.create_label",
    "shipping.track"
  ]
}

Response:

{
  "message": "Role updated successfully",
  "role": {
    "id": 6,
    "name": "senior warehouse manager",
    "description": "Updated description",
    "permissions_count": 7
  }
}

Note: System roles (owner, admin, manager, agent, viewer) cannot be modified.

Deleting a Custom Role

DELETE /api/v1/team/roles/{id}
Authorization: Bearer {token}
X-Tenant: my-store

Response:

{
  "message": "Role deleted successfully"
}

Requirements for deletion:

Role must be a custom role (not a system role)
No team members can be assigned to this role
If members are assigned, you must reassign them first

Listing Roles

GET /api/v1/team/roles
Authorization: Bearer {token}
X-Tenant: my-store

Response includes both system roles and tenant-specific custom roles:

{
  "roles": [
    {
      "id": 2,
      "name": "admin",
      "description": "Full administrative access",
      "is_system": true,
      "permissions_count": 66
    },
    {
      "id": 6,
      "name": "warehouse manager",
      "description": "Manages inventory and shipping",
      "is_system": false,
      "permissions_count": 5
    }
  ]
}

Role Details with Permissions

GET /api/v1/team/roles/{id}
Authorization: Bearer {token}
X-Tenant: my-store

Response includes all assigned permissions grouped by category:

{
  "role": {
    "id": 6,
    "name": "warehouse manager",
    "description": "Manages inventory and shipping",
    "is_system": false
  },
  "permission_groups": [
    {
      "id": 4,
      "slug": "products",
      "name": "Products",
      "icon": "cube",
      "permissions": [
        {
          "id": 20,
          "name": "products.view",
          "description": "View product catalog",
          "is_sensitive": false
        }
      ]
    }
  ]
}

Best Practices

Principle of Least Privilege: Start users with the Viewer role and upgrade as needed
Use Manager for Team Leads: Managers have enough access for operations without sensitive permissions
Reserve Admin for Trusted Staff: Admin can manage the team and integrations
Never Share Owner Credentials: The owner account should be secured with 2FA
Audit Regularly: Review role assignments monthly using the activity log