Team Management

Teams are the primary unit of organization within Atlas Auth Guard. They group users together and control access to backend services.

---

What is a Team?

A team is a logical grouping that:

• Groups users who work together

• Contains projects for data isolation

• Controls service access via team policies

• Has its own administrators who manage members and projects

Example Team Structure

┌─────────────────────────────────────────────────────────────────────────────┐
│                        TEAM: Engineering                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  TEAM ADMINS                          TEAM MEMBERS                          │
│  ════════════                         ════════════                          │
│  • [email protected]                   • [email protected]                    │
│  • [email protected]                     • [email protected]                     │
│                                       • [email protected]                      │
│                                                                              │
│  PROJECTS                                                                   │
│  ════════                                                                   │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐ │
│  │    LLM API          │  │    Auto Rater       │  │    CLI Eval         │ │
│  │    ───────          │  │    ──────────       │  │    ────────         │ │
│  │    API Key: sk-llm  │  │    API Key: sk-rate │  │    API Key: sk-cli  │ │
│  │    Members: 3       │  │    Members: 2       │  │    Members: 5       │ │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────┘ │
│                                                                              │
│  SERVICE POLICY                                                             │
│  ══════════════                                                             │
│  Allowed Services:                                                          │
│  ✅ llm-service                                                              │
│  ✅ auto-rater                                                               │
│  ✅ cli-eval                                                                 │
│  ✅ atlas-al-oss-svc                                                         │
│  ❌ analytics (not allowed)                                                  │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Team Roles

team_admin

Team administrators have full control over the team:

Capability	Description
Manage Members	Add/remove users, change roles
Create Projects	Create new projects within the team
Delete Projects	Remove projects (with all data)
Manage API Keys	Create/revoke API keys for the team
Configure Policy	Set which services the team can access
Implicit Project Access	Automatically has access to all projects in the team

team_member

Basic team members have limited access:

Capability	Description
View Team	See team information and member list
Access Projects	Access projects they're explicitly assigned to
Execute Services	Call backend services allowed by team policy
Cannot Manage	Cannot add members, create projects, or change settings

---

Team Service Policy

Every team has a service access policy that controls which backend services team members can use.

How It Works

User makes request to /v1/llm/generate
                │
                ▼
┌───────────────────────────────────────────────────────────┐
│            TEAM POLICY CHECK                               │
│                                                            │
│  User's Team: Engineering                                  │
│  Allowed Services: [llm, auto-rater, oss]                  │
│  Requested Service: llm                                    │
│                                                            │
│  Is "llm" in allowed_services?                             │
│  ✅ YES → Allow request                                     │
│  ❌ NO  → 403 Forbidden                                     │
└───────────────────────────────────────────────────────────┘

Policy Examples

Engineering Team - Full access to AI services:

allowed_services: ["llm", "auto-rater", "cot", "atlas-al-oss-svc"]

Data Science Team - Limited to analytics:

allowed_services: ["analytics", "llm"]

External Partner Team - Restricted access:

allowed_services: ["llm"]

Who Bypasses Team Policy?

Role	Bypasses Policy?	Reason
super_admin	✅ Yes	Platform-wide access
org_admin	✅ Yes	Organization-wide access
team_admin	❌ No	Still subject to team policy
team_member	❌ No	Subject to team policy

---

Managing Team Members

Adding a Member

When you add a user to a team:

1. User must exist in the organization (same email domain)

2. Specify their role: team_admin or team_member

3. User will see the team in their dashboard after re-login

4. User can now be added to projects within the team

Member Assignment Options

Method	Description
By User ID	Add existing user by their UUID
By Email	Add user by email address
Bulk Add	Add multiple users at once

Removing a Member

⚠️ Important Behavior:

When you remove a user from a team:

• User loses access to all projects in that team

• User's project role assignments are deleted

• User must be re-added to both team and projects to regain access

Before Removal:
├── Team: Engineering
│   ├── User: alice (team_member)
│   └── Project: LLM API
│       └── User: alice (editor)

After Removing alice from Engineering:
├── Team: Engineering
│   └── Project: LLM API
│       └── (alice removed from project too)

Changing Roles

Action	Effect
Promote to team_admin	User gains project management rights
Demote to team_member	User loses management rights but keeps project access

---

Team Status

Teams can have different statuses:

Status	Description	Effect
active	Normal operation	Full access
inactive	Temporarily disabled	Members cannot access
archived	Soft deleted	Hidden from lists, data preserved

---

Admin Dashboard Features

Access team management at: /admin/teams

Team List View

Column	Description
Name	Team name
Description	Team description
Members	Number of team members
Projects	Number of projects
Status	active/inactive
Created	Creation date

Team Detail View

Tab	Features
Overview	Team info, stats, quick actions
Members	List members, add/remove, change roles
Projects	List projects, create new
Policy	Configure allowed services
Settings	Edit name, description, status

---

Common Scenarios

Scenario 1: New Employee Onboarding

1. Admin invites user via email
2. User logs in for the first time
3. Admin adds user to appropriate team
4. Admin adds user to specific projects
5. User can now access team services

Scenario 2: User Needs Access to New Service

Problem: User gets "403 Forbidden: Service not allowed"

Solution:
1. Go to Admin → Teams → Select Team → Policy
2. Add the service to allowed_services
3. Save changes
4. User can now access the service (no re-login needed)

Scenario 3: Employee Leaves Team

1. Remove user from team in Admin Dashboard
2. User automatically loses all project access
3. Consider revoking any API keys they created
4. User's JWT remains valid until expiration (max 24h)

Scenario 4: Creating a New Team

1. Go to Admin → Teams → Create Team
2. Enter name and description
3. Configure service policy (which services to allow)
4. Add team admins
5. Add team members
6. Create projects as needed

---

Best Practices

Team Structure

Practice	Reason
One team per department/function	Clear ownership and responsibility
Keep teams small (5-20 members)	Easier to manage
Use descriptive names	"Engineering" not "Team 1"
Document team purpose	Use description field

Member Management

Practice	Reason
Limit team_admins to 2-3	Prevent configuration conflicts
Review membership quarterly	Remove inactive users
Use project roles for fine-grained access	Don't make everyone team_admin

Service Policy

Practice	Reason
Start with minimal services	Add more as needed
Document why each service is allowed	Helps with audits
Review policy when adding new services	Ensure intentional access

---

Troubleshooting

"Service not allowed for this team"

Error: 403 Forbidden: Service 'xyz-svc' not allowed for team

Cause: The requested service is not in the team's allowed_services list.

Solution:

1. Go to Admin → Teams → Select Team → Policy

2. Add the service to allowed_services

3. Save changes

"You are not a member of this team"

Error: 403 Forbidden: You are not a member of this team

Cause: User's JWT contains a team_id they're not a member of.

Solution:

1. Add user to the team, OR

2. User needs to re-login to get a fresh JWT with correct team

"Insufficient permissions to manage team"

Error: 403 Forbidden: Insufficient permissions

Cause: User is team_member, not team_admin.

Solution:

1. Promote user to team_admin, OR

2. Have an existing team_admin make the change

"Cannot remove last team admin"

Error: 400 Bad Request: Cannot remove last team admin

Cause: Trying to remove or demote the only team_admin.

Solution:

1. First promote another member to team_admin

2. Then remove/demote the original admin