> ## Documentation Index > Fetch the complete documentation index at: https://docs.junis.ai/llms.txt > Use this file to discover all available pages before exploring further. # Team Management Guide > Invite members, manage roles, and configure permissions for your organization ## What You'll Learn This guide covers comprehensive team management in Junis: * **Inviting Members**: Add team members via email invitation * **Role Management**: Assign and update roles (OWNER, ADMIN, MEMBER) * **Permission Control**: Configure granular permissions for each member * **Invitation Flow**: Manage pending invitations and acceptance process * **Member Removal**: Remove members with proper safeguards * **Best Practices**: Organize your team structure effectively **Prerequisites**: You must be an **OWNER** or **ADMIN** with `members.invite` permission to invite team members. *** ## Team Member Roles ### Role Hierarchy Junis uses a 3-tier role system with inherited permissions: ```mermaid theme={null} graph TD A[OWNER] --> B[Full Control] C[ADMIN] --> D[Almost Full Control] E[MEMBER] --> F[Limited Access] A --> I[Cannot be removed] A --> J[Can delete organization] C --> K[Cannot delete organization] E --> L[Default role for new members] ``` ### Role Comparison Matrix | Feature | OWNER | ADMIN | MEMBER | | ------------------- | ----- | ----- | ------ | | **Agents** | | | | | Create agents | ✅ | ✅ | ❌ | | Edit own agents | ✅ | ✅ | ✅ | | Edit all agents | ✅ | ✅ | ❌ | | Delete agents | ✅ | ✅ | ❌ | | View all agents | ✅ | ✅ | ✅ | | **Members** | | | | | Invite members | ✅ | ✅ | ❌ | | Remove members | ✅ | ✅ | ❌ | | Edit permissions | ✅ | ✅ | ❌ | | **Organization** | | | | | Edit settings | ✅ | ✅ | ❌ | | View analytics | ✅ | ✅ | ❌ | | Delete organization | ✅ | ❌ | ❌ | | **Sessions & Chat** | | | | | Create sessions | ✅ | ✅ | ✅ | | View own sessions | ✅ | ✅ | ✅ | | View all sessions | ✅ | ✅ | ❌ | **OWNER Role Protection**: Every organization must have at least one OWNER. The last OWNER cannot be removed or demoted. *** ## Inviting Team Members ### Email-Based Invitation Junis uses an email-based invitation system: Go to **Team > Members** in your organization dashboard. Click the **"Invite Member"** button in the top-right corner. Fill in the invitation form: * **Email**: Member's email address (required) * **Role**: Select initial role (ADMIN or MEMBER) * **Custom Permissions**: (Optional) Customize permissions for this member Click **"Send Invitation"** to create the invitation. ### Invitation Flow ```mermaid theme={null} sequenceDiagram participant Admin as Admin/Owner participant Platform as Junis Platform participant Invitee as New Member Admin->>Platform: Invite member (email + role) Platform->>Platform: Create PENDING member record Platform-->>Admin: Invitation sent Invitee->>Platform: Sign up with invited email Platform->>Platform: Link user_id to member record Platform->>Platform: Update status to ACTIVE Platform-->>Invitee: Welcome! Access granted Note over Invitee,Platform: Member can now access organization ``` ### Invitation States **Member Invited but Not Signed Up** **What Happens**: * Member record created with email * `user_id` is NULL * Status is `PENDING` * Member cannot access organization yet **What Shows in UI**: * Grey status badge: "Pending Invitation" * Email shown, no avatar * "Resend Invitation" button available * "Cancel Invitation" button available **How to Resolve**: 1. Invitee signs up with the invited email 2. System automatically links `user_id` and activates membership 3. Status changes to `ACTIVE` **Member Has Access** **What Happens**: * Member record linked to user account * `user_id` is set * Status is `ACTIVE` * Member can access organization resources **What Shows in UI**: * Green status badge: "Active" * Avatar and name displayed * "Edit Role" and "Remove" buttons available * Last active timestamp shown **Permissions Apply**: * Member can perform actions based on role and custom permissions **Member Temporarily Blocked** **What Happens**: * Member exists but access is revoked * Status is `SUSPENDED` * Member cannot log in or access resources **What Shows in UI**: * Red status badge: "Suspended" * "Reactivate" button available (OWNER/ADMIN only) * Greyed-out avatar **Use Cases**: * Temporary access removal (e.g., leave of absence) * Security investigation * Pending offboarding *** ## Managing Roles and Permissions ### Changing Member Roles Go to **Team > Members**. Click the **"Edit"** icon next to the member's name. In the edit dialog: * Select new role from dropdown * Choose whether to apply default permissions for the new role * Click **"Save Changes"** Review the confirmation dialog showing permission changes. Click **"Confirm"** to apply. **Role Change Impact**: * Changing role **overwrites custom permissions** if you check "Apply default permissions" * Member will immediately gain/lose access based on new role * Sessions in progress will be affected on next request ### Default Permissions by Role #### OWNER Permissions ```json theme={null} { "agents": { "create": true, "edit": true, "delete": true, "view_all": true }, "members": { "invite": true, "remove": true, "edit_permissions": true }, "organization": { "edit_settings": true, "view_analytics": true, "delete": true } } ``` **OWNER Role**: Cannot be customized. Always has full permissions. #### ADMIN Permissions ```json theme={null} { "agents": { "create": true, "edit": true, "delete": true, "view_all": true }, "members": { "invite": true, "remove": true, "edit_permissions": true }, "organization": { "edit_settings": true, "view_analytics": true, "delete": false // ← Cannot delete organization } } ``` **ADMIN Difference**: Almost identical to OWNER, but cannot delete the organization. #### MEMBER Permissions ```json theme={null} { "agents": { "create": false, // ← Cannot create new agents "edit": true, // ← Can edit own agents "delete": false, // ← Cannot delete agents "view_all": true }, "members": { "invite": false, "remove": false, "edit_permissions": false }, "organization": { "edit_settings": false, "view_analytics": false, "delete": false } } ``` **MEMBER Role**: Default role for new team members. Can edit own agents but cannot create new agents or manage other members. *** ## Custom Permissions ### Granular Permission Control Beyond roles, you can customize individual permissions for specific members. ### Permission Structure ```json theme={null} { "agents": { "create": boolean, // Can create new agents "edit": boolean, // Can edit all agents (not just own) "delete": boolean, // Can delete all agents (not just own) "view_all": boolean // Can view all agents }, "members": { "invite": boolean, // Can invite new members "remove": boolean, // Can remove members "edit_permissions": boolean // Can edit member permissions }, "organization": { "edit_settings": boolean, // Can edit organization settings "view_analytics": boolean, // Can view usage analytics "delete": boolean // Can delete organization (OWNER only) } } ``` ### How to Set Custom Permissions **Steps**: 1. Go to **Team > Members** 2. Click **"Edit"** on member 3. Select role (e.g., MEMBER) 4. Uncheck **"Apply default permissions"** 5. Toggle individual permission switches 6. Click **"Save"** **Example Use Case**: * Member role but allow viewing analytics * Admin role but restrict agent deletion **Endpoint**: `PUT /api/organizations/{org_id}/members/{member_id}` **Request Body**: ```json theme={null} { "role": "MEMBER", "permissions": { "agents": { "create": false, "edit": true, "delete": false, "view_all": true }, "members": { "invite": false, "remove": false, "edit_permissions": false }, "organization": { "edit_settings": false, "view_analytics": true, // ← Custom: Allow analytics "delete": false } } } ``` **Response**: ```json theme={null} { "id": "member-uuid-1234", "email": "analyst@company.com", "role": "MEMBER", "permissions": { /* updated permissions */ }, "status": "ACTIVE" } ``` ### Common Custom Permission Patterns **MEMBER + view\_analytics** * Can edit own agents (default MEMBER permission) * Can view analytics dashboard (custom) * Cannot create new agents * Cannot invite members **Use Case**: Data analysts who need insights but not admin control **MEMBER + create agents** * Can create new agents (custom) * Can edit own agents (default MEMBER permission) * Cannot delete agents * Cannot manage members **Use Case**: Developers who need to create agents but not manage team **MEMBER + invite members** * Can edit own agents (default MEMBER permission) * Can invite new members (custom) * Cannot edit permissions * Cannot edit organization settings **Use Case**: Team leads who can grow the team but not configure org-level settings **ADMIN - delete agents** * Full admin permissions * Cannot delete agents (safety measure) * Can edit settings * Can invite members **Use Case**: Admins in regulated environments where agent deletion requires approval *** ## Managing Pending Invitations ### Viewing Pending Invitations Go to **Team > Members**. Use the status filter dropdown and select **"Pending"**. Pending invitations show: * Email address (no avatar) * Role assigned * "Pending Invitation" badge * Invited date * Invited by (admin name) ### Resending Invitations If an invitee didn't receive the invitation email: Click the **"Resend Invitation"** button next to the member. **Email Delivery**: Invitation emails may take up to 5 minutes to arrive. Check spam folder if not received. ### Canceling Invitations To cancel a pending invitation: Go to **Team > Members** and filter by "Pending". Click the **"Cancel Invitation"** button. Confirm in the dialog. The invitation will be permanently removed. **Permanent Deletion**: Canceling an invitation deletes the member record. You'll need to re-invite if you change your mind. ### Invitee Acceptance Flow When an invitee signs up: ```mermaid theme={null} sequenceDiagram participant Invitee as New User participant Platform as Junis Platform participant Database as Database participant Org as Organization Invitee->>Platform: Sign up with invited email Platform->>Database: Check for pending invitation Database-->>Platform: Found: member record (PENDING) Platform->>Database: Link user_id to member Platform->>Database: Update status to ACTIVE Platform->>Org: Grant access to organization Platform-->>Invitee: Welcome! Redirect to organization Note over Invitee,Org: Member can now access agents, sessions, etc. ``` **Automatic Activation**: No manual approval needed. As soon as the invitee signs up, they gain access. *** ## Removing Members ### Safe Member Removal Go to **Team > Members**. Click the **"Remove"** button next to the member's name. A confirmation dialog shows: * Member name and email * Number of agents they created * Number of active sessions * Warning if last OWNER Click **"Remove Member"** to confirm. ### What Happens When a Member is Removed **Access Revoked**: * Member cannot access organization immediately * Active sessions are terminated on next request * WebSocket connections are closed * API tokens no longer valid for this organization **Data Retention**: * Agents created by member remain (ownership transferred to OWNER) * Sessions created by member remain (for audit trail) * Chat history preserved **Member Record**: * Deleted from `organization_members` table (CASCADE delete) * No longer appears in members list * Cannot be restored (must re-invite) **Related Resources**: * Agents: `created_by` updated to organization OWNER * Sessions: Remain unchanged (for audit) * API Keys: Invalidated if scoped to this member **If Removed Member Rejoins**: * Must be re-invited (new invitation) * Gets new member record (new UUID) * Loses previous custom permissions (new role/permissions assigned) * Previous agent ownership not restored ### Last OWNER Protection **Cannot Remove Last OWNER**: * Every organization must have at least one OWNER * Attempting to remove the last OWNER triggers an error: ```json theme={null} { "error": "Cannot remove the last owner of the organization", "code": "LAST_OWNER_PROTECTION" } ``` **Solution**: Promote another member to OWNER first, then remove the original OWNER. ### Suspending vs Removing | Action | Access Revoked | Data Deleted | Reversible | Use Case | | ----------- | -------------- | --------------------- | --------------------- | ------------------------------ | | **Suspend** | ✅ Yes | ❌ No | ✅ Yes (Reactivate) | Temporary leave, investigation | | **Remove** | ✅ Yes | ✅ Yes (member record) | ❌ No (must re-invite) | Permanent departure | **Suspension** (coming soon): Use suspension for temporary access removal. Use removal for permanent offboarding. *** ## Team Structure Best Practices ### Recommended Team Sizes **Structure**: * 1 OWNER (founder or technical lead) * 1-2 ADMIN (co-founders or senior engineers) * Remaining as MEMBER (developers, analysts) **Permissions Strategy**: * Keep it simple: use default permissions * Grant custom permissions as needed (e.g., MEMBER + create agents) * Admins handle member management **Example**: ``` OWNER: alice@startup.com (CEO) ADMIN: bob@startup.com (CTO) MEMBER: charlie@startup.com (Engineer, custom: + create agents) MEMBER: diana@startup.com (Data Analyst, custom: + view_analytics) ``` **Structure**: * 1 OWNER (organization admin) * 3-5 ADMIN (team leads) * Most as MEMBER (engineers, analysts, designers) * External stakeholders as MEMBER with read-only custom permissions **Permissions Strategy**: * Use custom permissions for team leads (MEMBER + invite + create agents) * Restrict agent deletion to ADMIN only * Grant read-only permissions to external stakeholders **Example**: ``` OWNER: admin@company.com ADMIN: engineering-lead@company.com ADMIN: data-lead@company.com MEMBER: developer-1@company.com (custom: + invite + create agents) MEMBER: developer-2@company.com (custom: + create agents) MEMBER: analyst-1@company.com (custom: + view_analytics) MEMBER: client@external.com (custom: read-only, no create/edit) ``` **Structure**: * 1 OWNER (platform admin) * 5-10 ADMIN (department leads) * Bulk as MEMBER (department members) * External stakeholders as MEMBER with read-only permissions **Permissions Strategy**: * Use sub-teams (feature: coming soon) * Strict permission controls * Custom roles for specialized access * Dedicated admin for member management **Example**: ``` OWNER: platform-admin@enterprise.com ADMIN: ai-team-lead@enterprise.com ADMIN: data-team-lead@enterprise.com ADMIN: product-lead@enterprise.com MEMBER: ai-engineer-1@enterprise.com (custom: + create agents) MEMBER: ai-engineer-2@enterprise.com (custom: + create agents) MEMBER: data-scientist-1@enterprise.com (custom: + view_analytics) MEMBER: product-manager-1@enterprise.com (custom: + create agents) MEMBER: executive@enterprise.com (custom: read-only) MEMBER: partner@external.com (custom: read-only) ``` ### Role Assignment Guidelines **Assign OWNER to**: * Organization creator * Ultimate decision maker * Person responsible for billing * Most trusted individual **Limit to**: 1-2 people (minimize risk) **Assign ADMIN to**: * Team leads * Senior engineers * Department heads * Trusted power users **Limit to**: 10-15% of team size **Assign MEMBER to**: * Regular engineers * Analysts * Designers * Most contributors * External stakeholders (with custom read-only permissions) **Default role**: 80-90% of team ### Permission Management Tips **✅ DO**: * Start with default permissions for each role * Grant least privilege (minimum permissions needed) * Review permissions quarterly * Use custom permissions sparingly * Document why custom permissions were granted * Revoke permissions immediately upon offboarding **❌ DON'T**: * Give everyone ADMIN role "just in case" * Grant organization deletion permission liberally * Use custom permissions without documentation * Leave pending invitations indefinitely * Forget to remove members who leave *** ## Troubleshooting Common Issues **Symptoms**: Member invited but email not received **Possible Causes**: * Email in spam folder * Email delivery delay (up to 5 minutes) * Typo in email address * Email provider blocking automated emails **Solutions**: 1. Check spam/junk folder 2. Wait 5-10 minutes and check again 3. Verify email address is correct (cancel and re-invite if typo) 4. Resend invitation from members list 5. Contact support if issue persists **Symptoms**: "Remove Member" button is disabled or shows error **Possible Causes**: * Trying to remove last OWNER * Insufficient permissions (not OWNER/ADMIN) * Member is yourself (cannot self-remove OWNER) **Solutions**: * **Last OWNER**: Promote another member to OWNER first * **Permissions**: Ask an ADMIN or OWNER to remove * **Self-removal**: Ask another ADMIN/OWNER to remove you **Symptoms**: Member cannot perform expected actions **Debugging Steps**: 1. Check member's role in **Team > Members** 2. Verify custom permissions (if any) 3. Check organization status (must be ACTIVE) 4. Verify member status is ACTIVE (not PENDING or SUSPENDED) **Solutions**: * Update role to appropriate level * Add custom permissions if needed * Reactivate member if suspended * Wait for organization approval if PENDING **Symptoms**: User signed up but still shows PENDING **Possible Causes**: * User signed up with different email * Email case mismatch ([user@example.com](mailto:user@example.com) vs [User@example.com](mailto:User@example.com)) * Database sync delay **Solutions**: 1. Verify user signed up with exact email from invitation 2. Check for case sensitivity (emails should be case-insensitive) 3. Wait 1-2 minutes for database sync 4. Cancel invitation and re-invite with correct email 5. Contact support if issue persists **Symptoms**: Members list cluttered with old pending invitations **Cleanup Steps**: 1. Go to **Team > Members** 2. Filter by "Pending" status 3. Sort by "Invited Date" (oldest first) 4. Cancel invitations older than 30 days 5. Resend invitations for current team members **Prevention**: * Cancel invitations after 7 days of no response * Follow up via personal email * Use expiration dates (feature: coming soon) *** ## API Reference for Team Management ### List Organization Members **Endpoint**: `GET /api/organizations/{organization_id}/members` **Authentication**: Bearer token required **Query Parameters**: * `status` (optional): Filter by status (PENDING, ACTIVE, SUSPENDED) * `role` (optional): Filter by role (OWNER, ADMIN, MEMBER) **Response**: ```json theme={null} { "members": [ { "id": "member-uuid-1234", "email": "alice@company.com", "user_id": "user-uuid-5678", "role": "OWNER", "status": "ACTIVE", "permissions": { /* full permissions */ }, "invited_by": "system", "invited_at": "2026-01-01T00:00:00Z", "joined_at": "2026-01-01T00:05:00Z", "last_active_at": "2026-01-01T15:30:00Z" }, { "id": "member-uuid-9012", "email": "bob@company.com", "user_id": null, "role": "MEMBER", "status": "PENDING", "permissions": { /* default MEMBER permissions */ }, "invited_by": "user-uuid-5678", "invited_at": "2026-01-01T10:00:00Z", "joined_at": null, "last_active_at": null } ], "total": 2 } ``` ### Invite Member **Endpoint**: `POST /api/organizations/{organization_id}/members` **Authentication**: Bearer token with `members.invite` permission **Request Body**: ```json theme={null} { "email": "newmember@company.com", "role": "MEMBER", "permissions": { // Optional: custom permissions // If omitted, default permissions for role are applied } } ``` **Response**: ```json theme={null} { "id": "member-uuid-3456", "email": "newmember@company.com", "user_id": null, "role": "MEMBER", "status": "PENDING", "permissions": { /* default MEMBER permissions */ }, "invited_by": "user-uuid-5678", "invited_at": "2026-01-01T16:00:00Z" } ``` ### Update Member Role **Endpoint**: `PUT /api/organizations/{organization_id}/members/{member_id}` **Authentication**: Bearer token with `members.edit_permissions` permission **Request Body**: ```json theme={null} { "role": "ADMIN", "permissions": { // Optional: custom permissions // If omitted, default permissions for new role are applied } } ``` **Response**: ```json theme={null} { "id": "member-uuid-3456", "email": "newmember@company.com", "user_id": "user-uuid-7890", "role": "ADMIN", "status": "ACTIVE", "permissions": { /* updated permissions */ }, "updated_at": "2026-01-01T16:30:00Z" } ``` ### Remove Member **Endpoint**: `DELETE /api/organizations/{organization_id}/members/{member_id}` **Authentication**: Bearer token with `members.remove` permission **Response**: ```json theme={null} { "message": "Member removed successfully", "removed_member_id": "member-uuid-3456" } ``` **Error (Last OWNER)**: ```json theme={null} { "error": "Cannot remove the last owner of the organization", "code": "LAST_OWNER_PROTECTION" } ``` *** ## What's Next? Learn how to manage multiple organizations effectively Access admin dashboard for API key and organization settings *** ## Additional Resources * **Organization API Reference**: Full API documentation for all organization endpoints * **Permission Schema**: Detailed permission structure and validation rules * **Security Best Practices**: Guidelines for secure team management * **Audit Logs**: Track member activity and permission changes (feature: coming soon) **Need Help?** Contact your organization OWNER or Junis support at [contact@junis.ai](mailto:contact@junis.ai) for assistance with team management.