Collaborator Roles, Permissions & Account Management

🔍 Problem Statement

As a Pelcro Account Owner or Admin, I experience a lack of granular access controls and compliance tooling for Collaborator accounts, which results in over-privileged users, security audit failures, and operational risk when managing internal team access.

Specifically:

• Deletion authority is too broad — any collaborator can delete other collaborators; this should be restricted to the Account Owner only.

• No intermediate role exists — CSRs and Sales reps must be granted full Admin access to perform basic tasks (updating customer info, creating plans, voiding invoices), exposing them to sensitive areas they should not access.

• No inactive/suspended state — the only option to remove access is to delete the account entirely, which revokes any associated API keys and breaks integrations.

• No last login visibility — admins cannot identify inactive or dormant collaborator accounts, making periodic security reviews manual and error-prone.

• No collaborator export — the collaborator list cannot be exported, sorted, or filtered, making bulk compliance reviews impractical.

💡 User Stories

1. Granular Role Permissions
As a Pelcro Account Owner, I want only Account Owners to be able to delete collaborator accounts, so that collaborators cannot be accidentally or maliciously removed by other team members.

2. Intermediate Role for CSRs
As a Customer Service Representative, I want a role that allows me to update customer information and void or cancel invoices, so that I can resolve customer issues without being granted full Admin access to sensitive product and access control settings.

3. Sales Role Capabilities
As a Sales collaborator, I want to be able to create and edit plans and export customer, subscription, and invoice data, so that I can perform quoting and reporting workflows without requiring Admin privileges.

4. Inactive Account State
As an Account Owner or Admin, I want to mark a collaborator account as inactive (suspended) without deleting it, so that I can revoke access for employees on extended leave or disability while preserving their account data and any associated API keys.

5. Last Login Visibility
As an Account Owner or Admin, I want to see the last login timestamp for each collaborator, so that I can identify dormant or inactive accounts during periodic security and compliance reviews.

6. Collaborator Account Export
As an Account Owner or Admin, I want to export the full collaborator list (including role, status, last login, and email), so that I can perform bulk access reviews, identify accounts to deactivate, and meet auditor requirements without manually paginating through the UI.

🎯 Definition of Done (DoD)

Roles & Permissions

• ✔ Given a collaborator with a non-Owner role, when they attempt to delete another collaborator, then the API returns a 403 Forbidden permission denied error and the UI surfaces a clear message.

• ✔ Given the updated permission matrix, when a Sales collaborator is logged in, then they can create/edit plans and export customers, subscriptions, and invoices — but cannot access access control, product settings, or delete any object.

• ✔ Given the updated permission matrix, when a Customer Service collaborator is logged in, then they can void and cancel invoices and update customer info — but cannot access plans, access controls, or delete any object.

• ✔ This change will impact API + UI, specifically the collaborator permissions schema, all relevant API endpoints (role enforcement middleware), and the Collaborators management UI.

• ✔ Permission matrix is encoded in code/schema with migrations applied. Automated tests verify all role boundaries. API returns structured authorization_error responses for disallowed actions.

• ✔ UPGRADE THE USER INTERFACE TO NEW DESIGN.

Inactive Account State

• ✔ Given an active collaborator account, when an Account Owner or Admin marks it as inactive, then the collaborator can no longer log in, but their account record and all associated API keys are preserved.

• ✔ Given a reactivation action, when an Account Owner or Admin restores the collaborator, then login and API key access are fully restored.

• ✔ This change will impact API + UI, specifically GET/PATCH /collaborators/{id} (new status field) and the Collaborators list/detail UI.

• ✔ Limitations: inactive collaborators cannot be used for SSO; API keys belonging to inactive collaborators remain valid at the key level but the collaborator session is blocked.

Last Login Visibility

• ✔ Given any collaborator account, when an Account Owner or Admin views the collaborator list or detail, then a lastLoginAt timestamp (ISO 8601, UTC) is displayed.

• ✔ This change will impact API + UI, specifically GET /collaborators and GET /collaborators/{id} response schemas, and the Collaborators list UI column.

• ✔ Limitations: last login reflects the most recent session start; it does not track individual action timestamps.

Collaborator Export

• ✔ Given the Collaborators management page, when an Account Owner or Admin triggers an export, then a CSV/XLSX file is generated containing: name, email, role, status (active/inactive), last login, and account creation date.

• ✔ This change will impact API + UI, specifically a new GET /collaborators/export endpoint and an export button in the Collaborators UI.

• ✔ All new API endpoints must be fully documented, tested, and covered by automated test cases per Pelcro's API-first DoD.

• ✔ Limitations: export is scoped to collaborators within the authenticated organization only; cross-org exports are not supported.

📋 Role Permission Matrix