Team Management Guide

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, VIEWER)
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 4-tier role system with inherited permissions:

Role Comparison Matrix

Feature	OWNER	ADMIN	MEMBER	VIEWER
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:

Navigate to Team Settings

Go to Team > Members in your organization dashboard.

Click 'Invite Member'

Click the “Invite Member” button in the top-right corner.

Enter Member Details

Fill in the invitation form:

Email: Member’s email address (required)
Role: Select initial role (ADMIN, MEMBER, or VIEWER)
Custom Permissions: (Optional) Customize permissions for this member

Send Invitation

Click “Send Invitation” to create the invitation.

Invitation Flow

Invitation States

PENDING
ACTIVE
SUSPENDED

Member Invited but Not Signed UpWhat 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:

Invitee signs up with the invited email
System automatically links user_id and activates membership
Status changes to ACTIVE

Managing Roles and Permissions

Changing Member Roles

Navigate to Members List

Go to Team > Members.

Select Member

Click the “Edit” icon next to the member’s name.

Update Role

In the edit dialog:

Select new role from dropdown
Choose whether to apply default permissions for the new role
Click “Save Changes”

Confirm 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

{
  "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

{
  "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

{
  "agents": {
    "create": true,
    "edit": false,     // ← Can only edit own agents
    "delete": false,   // ← Can only delete own 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 create agents but cannot manage other members.

VIEWER Permissions

{
  "agents": {
    "create": false,
    "edit": false,
    "delete": false,
    "view_all": true  // ← Read-only access
  },
  "members": {
    "invite": false,
    "remove": false,
    "edit_permissions": false
  },
  "organization": {
    "edit_settings": false,
    "view_analytics": false,
    "delete": false
  }
}

VIEWER Role: Read-only access. Cannot create or modify any resources.

Custom Permissions

Granular Permission Control

Beyond roles, you can customize individual permissions for specific members.

Permission Structure

{
  "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

Via Admin UI
Via API

Steps:

Go to Team > Members
Click “Edit” on member
Select role (e.g., MEMBER)
Uncheck “Apply default permissions”
Toggle individual permission switches
Click “Save”

Example Use Case:

Member role but allow viewing analytics
Admin role but restrict agent deletion

Common Custom Permission Patterns

Analyst Role

MEMBER + view_analytics

Can create agents
Can view analytics dashboard
Cannot invite members
Cannot edit organization settings

Use Case: Data analysts who need insights but not admin control

Developer Role

MEMBER + edit agents

Can create and edit all agents
Cannot delete agents
Cannot manage members
Can view all agents

Use Case: Developers who need to modify agents but not manage team

Manager Role

MEMBER + invite members

Can create agents
Can invite new members
Cannot edit permissions
Cannot edit organization settings

Use Case: Team leads who can grow the team but not configure org-level settings

Restricted Admin

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

Navigate to Members

Go to Team > Members.

Filter by Status

Use the status filter dropdown and select “Pending”.

View Details

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:

Find Pending Member

Filter members list by “Pending” status.

Click 'Resend'

Click the “Resend Invitation” button next to the member.

Confirm

A new invitation email will be sent.

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:

Find Pending Member

Go to Team > Members and filter by “Pending”.

Click 'Cancel'

Click the “Cancel Invitation” button.

Confirm Deletion

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:

Automatic Activation: No manual approval needed. As soon as the invitee signs up, they gain access.

Removing Members

Safe Member Removal

Navigate to Members

Go to Team > Members.

Select Member

Click the “Remove” button next to the member’s name.

Review Impact

A confirmation dialog shows:

Member name and email
Number of agents they created
Number of active sessions
Warning if last OWNER

Confirm Removal

Click “Remove Member” to confirm.

What Happens When a Member is Removed

Immediate Effects
Database Changes
Re-Invitation

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

Last OWNER Protection

Cannot Remove Last OWNER:

Every organization must have at least one OWNER
Attempting to remove the last OWNER triggers an error:

{
  "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

Small Team (1-10)
Medium Team (11-50)
Large Team (51+)

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
Everyone can create agents (MEMBER role)
Admins handle member management

Example:

OWNER:  [email protected] (CEO)
ADMIN:  [email protected] (CTO)
MEMBER: [email protected] (Engineer)
MEMBER: [email protected] (Data Analyst)

Role Assignment Guidelines

Who Should Be OWNER?

Assign OWNER to:

Organization creator
Ultimate decision maker
Person responsible for billing
Most trusted individual

Limit to: 1-2 people (minimize risk)

Who Should Be ADMIN?

Assign ADMIN to:

Team leads
Senior engineers
Department heads
Trusted power users

Limit to: 10-15% of team size

Who Should Be MEMBER?

Assign MEMBER to:

Regular engineers
Analysts
Designers
Most contributors

Default role: 70-80% of team

Who Should Be VIEWER?

Assign VIEWER to:

External stakeholders
Clients (demos)
Executives (read-only access)
Auditors

Limit to: Only when necessary

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

Invitee Didn't Receive Email

Symptoms: Member invited but email not receivedPossible Causes:

Email in spam folder
Email delivery delay (up to 5 minutes)
Typo in email address
Email provider blocking automated emails

Solutions:

Check spam/junk folder
Wait 5-10 minutes and check again
Verify email address is correct (cancel and re-invite if typo)
Resend invitation from members list
Contact support if issue persists

Cannot Remove Member

Symptoms: “Remove Member” button is disabled or shows errorPossible 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

Member Has Wrong Permissions

Symptoms: Member cannot perform expected actionsDebugging Steps:

Check member’s role in Team > Members
Verify custom permissions (if any)
Check organization status (must be ACTIVE)
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

Invitation Not Auto-Activating

Symptoms: User signed up but still shows PENDINGPossible Causes:

User signed up with different email
Email case mismatch ([email protected] vs [email protected])
Database sync delay

Solutions:

Verify user signed up with exact email from invitation
Check for case sensitivity (emails should be case-insensitive)
Wait 1-2 minutes for database sync
Cancel invitation and re-invite with correct email
Contact support if issue persists

Too Many Pending Invitations

Symptoms: Members list cluttered with old pending invitationsCleanup Steps:

Go to Team > Members
Filter by “Pending” status
Sort by “Invited Date” (oldest first)
Cancel invitations older than 30 days
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, VIEWER)

Response:

{
  "members": [
    {
      "id": "member-uuid-1234",
      "email": "[email protected]",
      "user_id": "user-uuid-5678",
      "role": "OWNER",
      "status": "ACTIVE",
      "permissions": { /* full permissions */ },
      "invited_by": "system",
      "invited_at": "2024-01-01T00:00:00Z",
      "joined_at": "2024-01-01T00:05:00Z",
      "last_active_at": "2024-01-10T15:30:00Z"
    },
    {
      "id": "member-uuid-9012",
      "email": "[email protected]",
      "user_id": null,
      "role": "MEMBER",
      "status": "PENDING",
      "permissions": { /* default MEMBER permissions */ },
      "invited_by": "user-uuid-5678",
      "invited_at": "2024-01-09T10: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:

{
  "email": "[email protected]",
  "role": "MEMBER",
  "permissions": {
    // Optional: custom permissions
    // If omitted, default permissions for role are applied
  }
}

Response:

{
  "id": "member-uuid-3456",
  "email": "[email protected]",
  "user_id": null,
  "role": "MEMBER",
  "status": "PENDING",
  "permissions": { /* default MEMBER permissions */ },
  "invited_by": "user-uuid-5678",
  "invited_at": "2024-01-10T16:00:00Z"
}

Update Member Role

Endpoint: PUT /api/organizations/{organization_id}/members/{member_id} Authentication: Bearer token with members.edit_permissions permission Request Body:

{
  "role": "ADMIN",
  "permissions": {
    // Optional: custom permissions
    // If omitted, default permissions for new role are applied
  }
}

Response:

{
  "id": "member-uuid-3456",
  "email": "[email protected]",
  "user_id": "user-uuid-7890",
  "role": "ADMIN",
  "status": "ACTIVE",
  "permissions": { /* updated permissions */ },
  "updated_at": "2024-01-10T16:30:00Z"
}

Remove Member

Endpoint: DELETE /api/organizations/{organization_id}/members/{member_id} Authentication: Bearer token with members.remove permission Response:

{
  "message": "Member removed successfully",
  "removed_member_id": "member-uuid-3456"
}

Error (Last OWNER):

{
  "error": "Cannot remove the last owner of the organization",
  "code": "LAST_OWNER_PROTECTION"
}

What’s Next?

Multi-Organization Setup

Learn how to manage multiple organizations effectively

Best Practices

Organization naming, security, and scaling strategies

Organization Overview

Back to organization system overview

API Keys Management

Manage API keys for programmatic access

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 [email protected] for assistance with team management.

User Guides

​What You’ll Learn

​Team Member Roles

​Role Hierarchy

​Role Comparison Matrix

​Inviting Team Members

​Email-Based Invitation

​Invitation Flow

​Invitation States

​Managing Roles and Permissions

​Changing Member Roles

​Default Permissions by Role

​OWNER Permissions

​ADMIN Permissions

​MEMBER Permissions

​VIEWER Permissions

​Custom Permissions

​Granular Permission Control

​Permission Structure

​How to Set Custom Permissions

​Common Custom Permission Patterns

Analyst Role

Developer Role

Manager Role

Restricted Admin

​Managing Pending Invitations

​Viewing Pending Invitations

​Resending Invitations

​Canceling Invitations

​Invitee Acceptance Flow

​Removing Members

​Safe Member Removal

​What Happens When a Member is Removed

​Last OWNER Protection

​Suspending vs Removing

​Team Structure Best Practices

​Recommended Team Sizes

​Role Assignment Guidelines

Who Should Be OWNER?

Who Should Be ADMIN?

Who Should Be MEMBER?

Who Should Be VIEWER?

​Permission Management Tips

​Troubleshooting Common Issues

​API Reference for Team Management

​List Organization Members

​Invite Member

​Update Member Role

​Remove Member

​What’s Next?

Multi-Organization Setup

Best Practices

Organization Overview

API Keys Management

​Additional Resources

What You’ll Learn

Team Member Roles

Role Hierarchy

Role Comparison Matrix

Inviting Team Members

Email-Based Invitation

Invitation Flow

Invitation States

Managing Roles and Permissions

Changing Member Roles

Default Permissions by Role

OWNER Permissions

ADMIN Permissions

MEMBER Permissions

VIEWER Permissions

Custom Permissions

Granular Permission Control

Permission Structure

How to Set Custom Permissions

Common Custom Permission Patterns

Managing Pending Invitations

Viewing Pending Invitations

Resending Invitations

Canceling Invitations

Invitee Acceptance Flow

Removing Members

Safe Member Removal

What Happens When a Member is Removed

Last OWNER Protection

Suspending vs Removing

Team Structure Best Practices

Recommended Team Sizes

Role Assignment Guidelines

Permission Management Tips

Troubleshooting Common Issues

API Reference for Team Management

List Organization Members

Invite Member

Update Member Role

Remove Member

What’s Next?

Additional Resources