Team Management

AutoCom provides comprehensive team management capabilities, allowing you to invite members, assign roles, and manage access across your organization.

Overview

Team management follows a simple workflow:

Owner/Admin ──► Send Invitation ──► User Accepts ──► Active Member
                     │
                     └── Assign Role ──► Permissions Applied

Inviting Team Members

Requirements

• You need the team.invite permission
• The email must not already be a member of this tenant
• You cannot invite with the Owner role

Send an Invitation

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

{
  "email": "jane@example.com",
  "role_id": 3
}

Response:

{
  "message": "Invitation sent successfully",
  "invitation": {
    "id": 1,
    "email": "jane@example.com",
    "role": "manager",
    "expires_at": "2024-01-08T12:00:00Z"
  }
}

Role IDs

ID	Role
2	Admin
3	Manager
4	Agent
5	Viewer

Note: Role ID 1 (Owner) cannot be assigned via invitation.

---

Accepting Invitations

Invitations are accepted via a public endpoint (no authentication required).

New User (Registration + Accept)

POST /api/v1/invitations/accept
Content-Type: application/json

{
  "token": "abc123...",
  "name": "Jane Doe",
  "password": "securepassword",
  "password_confirmation": "securepassword"
}

Existing User (Just Accept)

If the user already has an account, they just need the token:

POST /api/v1/invitations/accept
Content-Type: application/json

{
  "token": "abc123..."
}

Response:

{
  "message": "Successfully joined the organization",
  "user": {
    "id": 2,
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "tenant": {
    "id": "my-store"
  },
  "role": "manager",
  "access_token": "eyJ0eXAiOi...",
  "token_type": "Bearer"
}

---

Managing Invitations

List Pending Invitations

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

Response:

{
  "invitations": [
    {
      "id": 1,
      "email": "pending@example.com",
      "role": {
        "id": 4,
        "name": "agent"
      },
      "invited_by": {
        "id": 1,
        "name": "John Owner"
      },
      "expires_at": "2024-01-08T12:00:00Z",
      "created_at": "2024-01-01T12:00:00Z"
    }
  ]
}

Resend an Invitation

Generates a new token and extends expiry:

POST /api/v1/team/invitations/{id}/resend
Authorization: Bearer {token}
X-Tenant: my-store

Cancel an Invitation

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

---

Managing Team Members

List All Members

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

Response:

{
  "members": [
    {
      "id": 1,
      "user": {
        "id": 1,
        "name": "John Owner",
        "email": "john@mystore.com",
        "email_verified": true
      },
      "role": {
        "id": 1,
        "name": "owner",
        "description": "Full access owner role"
      },
      "status": "active",
      "joined_at": "2024-01-01T00:00:00Z",
      "last_active_at": "2024-01-07T15:30:00Z",
      "invited_by": null
    },
    {
      "id": 2,
      "user": {
        "id": 2,
        "name": "Jane Manager",
        "email": "jane@example.com",
        "email_verified": true
      },
      "role": {
        "id": 3,
        "name": "manager",
        "description": "Operational management role"
      },
      "status": "active",
      "joined_at": "2024-01-02T10:00:00Z",
      "last_active_at": "2024-01-07T14:00:00Z",
      "invited_by": {
        "id": 1,
        "name": "John Owner"
      }
    }
  ],
  "total": 2
}

Member Status

Status	Description
active	Member can access the organization
suspended	Member is temporarily blocked
pending	Invitation sent but not accepted

---

Changing Roles

Update a member's role:

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

{
  "role_id": 4
}

Restrictions

• Cannot change the Owner's role
• Cannot assign the Owner role to others
• Cannot change your own role

Response:

{
  "message": "Role updated successfully",
  "member": {
    "id": 2,
    "user": {
      "id": 2,
      "name": "Jane Manager"
    },
    "role": {
      "id": 4,
      "name": "agent"
    }
  }
}

---

Suspending Members

Temporarily block a member's access:

POST /api/v1/team/members/{id}/suspend
Authorization: Bearer {token}
X-Tenant: my-store

Restrictions

• Cannot suspend the Owner
• Cannot suspend yourself

Reactivating Suspended Members

POST /api/v1/team/members/{id}/reactivate
Authorization: Bearer {token}
X-Tenant: my-store

---

Removing Members

Permanently remove a member from the organization:

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

Restrictions

• Cannot remove the Owner
• Cannot remove yourself

Note: This only removes the tenant membership. The user account remains and can be re-invited.

---

Viewing Roles

List Available Roles

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

Response:

{
  "roles": [
    {
      "id": 2,
      "name": "admin",
      "description": "Full access to all features except billing",
      "is_system": true,
      "permissions_count": 66
    },
    {
      "id": 3,
      "name": "manager",
      "description": "Manage operations and team oversight",
      "is_system": true,
      "permissions_count": 39
    }
  ]
}

Note: The Owner role is not included in this list.

Get Role Details

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

Response:

{
  "role": {
    "id": 3,
    "name": "manager",
    "description": "Manage operations and team oversight",
    "is_system": true
  },
  "permission_groups": [
    {
      "id": 1,
      "slug": "dashboard",
      "name": "Dashboard",
      "icon": "layout-dashboard",
      "permissions": [
        {
          "id": 1,
          "name": "dashboard.view",
          "description": "View main dashboard",
          "is_sensitive": false
        }
      ]
    }
  ]
}

---

Best Practices

1. Start with Minimal Access

Invite new team members with the Viewer or Agent role. Upgrade access as needed based on their responsibilities.

2. Use Meaningful Role Assignments

Role	Recommended For
Admin	Department heads, senior managers
Manager	Team leads, shift supervisors
Agent	Support staff, order processors
Viewer	Investors, advisors, auditors

3. Regular Access Reviews

• Review team member access monthly
• Remove inactive members
• Downgrade roles for users who no longer need elevated access

4. Secure the Owner Account

• Enable two-factor authentication
• Don't share owner credentials
• Use a dedicated owner email address

5. Document Role Changes

Use the activity log to track who made role changes and when:

GET /api/v1/activity-logs?action=role_assigned

---

Multi-Tenant Considerations

Users can be members of multiple tenants with different roles in each:

User: jane@example.com
├── Tenant: store-a ──► Role: Admin
├── Tenant: store-b ──► Role: Agent
└── Tenant: store-c ──► Role: Viewer

Each tenant's team is completely isolated. Changes in one tenant don't affect others.