Admin API

This endpoint requires admin-level roles (platform_admin or super_admin).

User Groups API

Create and manage user groups for permission assignment and team organization.

Overview

User groups provide a way to organize users and assign permissions collectively. Groups can represent teams, departments, locations, or any logical grouping of users.

Feature	Description
Group CRUD	Create, read, update, delete groups
Membership	Add/remove users from groups
Permissions	Assign permissions to groups
Hierarchy	Nested group support
Tenant Scope	Groups are tenant-isolated

---

Group Model

{
  "id": "grp_abc123",
  "tenant_id": "tenant_xyz",
  "name": "Kitchen Staff",
  "description": "All kitchen personnel",
  "permissions": [
    "kds:read",
    "kds:bump",
    "orders:read"
  ],
  "parent_group_id": null,
  "metadata": {
    "department": "back-of-house",
    "location_ids": ["loc_001", "loc_002"]
  },
  "member_count": 12,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-18T14:30:00Z"
}

---

Endpoints

Create Group

POST /api/v1/auth/groups
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "name": "Kitchen Staff",
  "description": "All kitchen personnel",
  "permissions": ["kds:read", "kds:bump", "orders:read"],
  "parent_group_id": null,
  "metadata": {
    "department": "back-of-house"
  }
}

Response:

{
  "id": "grp_abc123",
  "name": "Kitchen Staff",
  "description": "All kitchen personnel",
  "permissions": ["kds:read", "kds:bump", "orders:read"],
  "member_count": 0,
  "created_at": "2026-01-18T14:30:00Z"
}

List Groups

GET /api/v1/auth/groups?page=1&limit=20
Authorization: Bearer {access_token}

Query Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
search	string	Search by name or description
parent_id	string	Filter by parent group

Response:

{
  "groups": [
    {
      "id": "grp_abc123",
      "name": "Kitchen Staff",
      "description": "All kitchen personnel",
      "member_count": 12
    },
    {
      "id": "grp_def456",
      "name": "Front of House",
      "description": "Servers and hosts",
      "member_count": 8
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1
  }
}

Get Group

GET /api/v1/auth/groups/{group_id}
Authorization: Bearer {access_token}

Response:

{
  "id": "grp_abc123",
  "tenant_id": "tenant_xyz",
  "name": "Kitchen Staff",
  "description": "All kitchen personnel",
  "permissions": ["kds:read", "kds:bump", "orders:read"],
  "parent_group_id": null,
  "metadata": {
    "department": "back-of-house"
  },
  "member_count": 12,
  "members": [
    {"user_id": "usr_001", "name": "John Doe", "role": "chef"},
    {"user_id": "usr_002", "name": "Jane Smith", "role": "line_cook"}
  ],
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-18T14:30:00Z"
}

Update Group

PATCH /api/v1/auth/groups/{group_id}
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "name": "Kitchen Team",
  "description": "Updated description",
  "permissions": ["kds:read", "kds:bump", "kds:write", "orders:read"]
}

Response:

{
  "id": "grp_abc123",
  "name": "Kitchen Team",
  "description": "Updated description",
  "permissions": ["kds:read", "kds:bump", "kds:write", "orders:read"],
  "updated_at": "2026-01-18T15:00:00Z"
}

Delete Group

DELETE /api/v1/auth/groups/{group_id}
Authorization: Bearer {access_token}

Response:

{
  "success": true,
  "message": "Group deleted successfully"
}

---

Membership Management

Add Member to Group

POST /api/v1/auth/groups/{group_id}/members
Authorization: Bearer {access_token}
Content-Type: application/json

Request:

{
  "user_id": "usr_abc123"
}

Response:

{
  "group_id": "grp_abc123",
  "user_id": "usr_abc123",
  "added_at": "2026-01-18T15:00:00Z"
}

Remove Member from Group

DELETE /api/v1/auth/groups/{group_id}/members/{user_id}
Authorization: Bearer {access_token}

Response:

{
  "success": true,
  "message": "User removed from group"
}

note

The following endpoints are not currently implemented in the auth service and should not be relied upon:

• GET /api/v1/auth/groups/{group_id}/members (list group members) -- members are returned inline in the GET /api/v1/auth/groups/{group_id} response
• POST /api/v1/auth/groups/{group_id}/members/bulk (bulk add members)
• PUT /api/v1/auth/groups/{group_id}/permissions (assign permissions to group)
• GET /api/v1/auth/users/{user_id}/groups (get user's groups)

Permissions are managed through the PATCH /api/v1/auth/groups/{group_id} endpoint by updating the permissions field on the group model.

---

Common Permissions

Permission	Description
orders:read	View orders
orders:write	Create/modify orders
orders:void	Void orders (manager)
payments:process	Process payments
payments:refund	Issue refunds (manager)
kds:read	View KDS tickets
kds:bump	Bump completed tickets
inventory:read	View inventory
inventory:write	Update stock levels
reports:read	View reports
staff:manage	Manage staff (manager)
settings:admin	Admin settings access

---

Error Codes

Code	Message	Description
GROUP_NOT_FOUND	Group not found	Invalid group ID
USER_NOT_FOUND	User not found	Invalid user ID for membership
USER_ALREADY_MEMBER	User already in group	Duplicate membership
PERMISSION_DENIED	Insufficient permissions	Not authorized
INVALID_PERMISSION	Invalid permission code	Permission doesn't exist

---

Best Practices

1. Use meaningful names - Name groups by function (e.g., "Kitchen Staff" not "Group 1")
2. Apply least privilege - Assign minimum required permissions
3. Use nested groups - Create hierarchy for complex organizations
4. Audit regularly - Review group membership periodically
5. Document purpose - Use description field to explain group purpose

---

Related Documentation

• RBAC & Roles - Role-based access control
• User Management - User administration
• Authentication Overview - Auth system overview