User Management

Users are individuals who access the Atlas Auth Guard system via Google OAuth authentication.

---

User Lifecycle

How Users Get Access

┌─────────────────────────────────────────────────────────────────────────────┐
│                        USER ONBOARDING FLOW                                  │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────────┐
  │ STEP 1: INVITATION                                                       │
  │                                                                          │
  │  Admin invites user via email                                            │
  │  • User record created with status: "invited"                            │
  │  • User assigned to a team with role                                     │
  │  • User optionally assigned to projects                                  │
  │                                                                          │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ STEP 2: FIRST LOGIN                                                      │
  │                                                                          │
  │  User clicks "Sign in with Google"                                       │
  │  • Google OAuth authentication                                           │
  │  • Auth Guard verifies email domain (@turing.com)                        │
  │  • Auth Guard looks up user by email                                     │
  │  • User found with status "invited" → Change to "active"                 │
  │  • Generate JWT with user context                                        │
  │                                                                          │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ STEP 3: ACTIVE USER                                                      │
  │                                                                          │
  │  User can now:                                                           │
  │  • Access teams they're assigned to                                      │
  │  • Access projects they're assigned to                                   │
  │  • Execute services allowed by team policy                               │
  │  • Use the admin dashboard                                               │
  │                                                                          │
  └─────────────────────────────────────────────────────────────────────────┘

User Status

Status	Description	Can Login?	Effect
invited	User has been invited but hasn't logged in yet	✅ Yes	Activates on first login
active	Normal active user	✅ Yes	Full access per roles
suspended	Temporarily disabled	❌ No	Cannot login, existing sessions expire
disabled	Permanently disabled	❌ No	Cannot login, account locked

---

Global Roles

Every user has a global role that defines their base level of access across the platform.

super_admin

The highest level of access - platform administrators.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        SUPER ADMIN CAPABILITIES                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ACCESS                                                                     │
│  ══════                                                                     │
│  ✅ Can access ALL organizations (if multi-org)                              │
│  ✅ Can access ALL teams without being a member                              │
│  ✅ Can access ALL projects without being a member                           │
│  ✅ Bypasses ALL team policies                                               │
│  ✅ Bypasses ALL membership checks                                           │
│                                                                              │
│  MANAGEMENT                                                                 │
│  ══════════                                                                 │
│  ✅ Can manage system service routes                                         │
│  ✅ Can manage system service policies                                       │
│  ✅ Can manage all users, teams, projects                                    │
│  ✅ Can perform all CRUD operations                                          │
│                                                                              │
│  VISIBILITY                                                                 │
│  ══════════                                                                 │
│  ✅ Sees all teams in /me/teams                                              │
│  ✅ Sees all projects in /me/projects                                        │
│  ✅ Full dashboard access                                                    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

org_admin

Organization-level administrators.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        ORG ADMIN CAPABILITIES                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ACCESS                                                                     │
│  ══════                                                                     │
│  ✅ Can access ALL teams in their organization                               │
│  ✅ Can access ALL projects in their organization                            │
│  ✅ Bypasses team policies within their org                                  │
│  ✅ Bypasses membership checks within their org                              │
│  ❌ Cannot access other organizations                                        │
│                                                                              │
│  MANAGEMENT                                                                 │
│  ══════════                                                                 │
│  ✅ Can manage service routes                                                │
│  ✅ Can manage service policies                                              │
│  ✅ Can manage all users in their org                                        │
│  ✅ Can manage all teams in their org                                        │
│  ✅ Can manage all projects in their org                                     │
│  ✅ Can perform delete operations                                            │
│                                                                              │
│  VISIBILITY                                                                 │
│  ══════════                                                                 │
│  ✅ Sees all teams in their org                                              │
│  ✅ Sees all projects in their org                                           │
│  ✅ Full dashboard access for their org                                      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

member

Basic organization member - the default role.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        MEMBER CAPABILITIES                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ACCESS                                                                     │
│  ══════                                                                     │
│  ✅ Can access teams they're explicitly added to                             │
│  ✅ Can access projects they're explicitly added to                          │
│  ❌ Subject to team policies                                                 │
│  ❌ Subject to membership checks                                             │
│                                                                              │
│  MANAGEMENT                                                                 │
│  ══════════                                                                 │
│  ❌ Cannot manage routes or policies                                         │
│  ❌ Cannot manage other users (unless team_admin)                            │
│  ⚠️ Can manage teams/projects if they have team_admin/project_admin role     │
│                                                                              │
│  VISIBILITY                                                                 │
│  ══════════                                                                 │
│  ✅ Sees only their own teams                                                │
│  ✅ Sees only their own projects                                             │
│  ⚠️ Dashboard access depends on team/project roles                           │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Effective Role Calculation

When a user accesses a resource, their effective role determines what they can do. The system uses the most specific role that applies.

Precedence Order

┌─────────────────────────────────────────────────────────────────────────────┐
│                     EFFECTIVE ROLE PRECEDENCE                                │
│                     (Most Specific Wins)                                     │
└─────────────────────────────────────────────────────────────────────────────┘

  1️⃣  EXPLICIT PROJECT ROLE (Highest Priority)
      ─────────────────────────────────────────
      If user has project_admin, editor, or viewer on THIS project,
      that role is used regardless of any other roles.

      Example: super_admin with viewer on Project X → viewer for Project X

  2️⃣  EXPLICIT TEAM ROLE (Medium Priority)
      ──────────────────────────────────────
      If user has team_admin or team_member on the project's team,
      that role applies to all projects in the team (unless #1 applies).

      Example: member with team_admin → team_admin for all team projects

  3️⃣  GLOBAL ROLE (Fallback)
      ────────────────────────
      If no explicit team or project role exists,
      the global role is used.

      Example: org_admin with no team membership → org_admin access

Examples

User	Global	Team Role	Project Role	Accessing Project X	Effective Role
Alice	super_admin	-	-	Any project	super_admin
Bob	super_admin	team_member	-	Project in that team	team_member
Carol	super_admin	team_admin	viewer	Project X	viewer
Dave	member	team_admin	-	Project in that team	team_admin
Eve	member	team_member	editor	Project X	editor
Frank	org_admin	-	-	Any project in org	org_admin

Key Insight

Global roles bypass ACCESS CHECKS but don't override EXPLICIT ROLE ASSIGNMENTS.

• super_admin can access any resource (bypasses team policy, membership checks)

• But if super_admin has viewer role on a project, their effective role is viewer

• This allows restricting sensitive projects even from admins

---

Permissions

Permissions are the specific actions a user can perform. They're derived from the effective role.

Permission List

Permission	Description
read:org	View organization details
write:org	Update organization settings
read:team	View team details
write:team	Create/update teams
delete:team	Delete teams
manage:team_users	Add/remove team members
read:project	View project details
write:project	Create/update projects
delete:project	Delete projects
manage:project_users	Add/remove project members
execute:services	Call backend services
read:api_keys	View API keys
write:api_keys	Create API keys
delete:api_keys	Revoke API keys
read:routes	View service routes
write:routes	Manage service routes
read:policies	View service policies
write:policies	Manage service policies

Role → Permission Matrix

Permission	super_admin	org_admin	team_admin	team_member	project_admin	editor	viewer
read:org	✅	✅	✅	✅	✅	✅	✅
write:org	✅	✅	❌	❌	❌	❌	❌
read:team	✅	✅	✅	✅	✅	✅	✅
write:team	✅	✅	✅	❌	❌	❌	❌
delete:team	✅	✅	❌	❌	❌	❌	❌
manage:team_users	✅	✅	✅	❌	❌	❌	❌
read:project	✅	✅	✅	✅	✅	✅	✅
write:project	✅	✅	✅	❌	✅	✅	❌
delete:project	✅	✅	✅	❌	❌	❌	❌
manage:project_users	✅	✅	✅	❌	✅	❌	❌
execute:services	✅	✅	✅	✅	✅	✅	❌
read:api_keys	✅	✅	✅	❌	✅	❌	❌
write:api_keys	✅	✅	✅	❌	✅	❌	❌
delete:api_keys	✅	✅	✅	❌	✅	❌	❌
read:routes	✅	✅	❌	❌	❌	❌	❌
write:routes	✅	✅	❌	❌	❌	❌	❌
read:policies	✅	✅	❌	❌	❌	❌	❌
write:policies	✅	✅	❌	❌	❌	❌	❌

---

JWT Token

After login, users receive a JWT token containing their context:

{
  "sub": "e9f7fca6-65d3-4be0-8374-07870b789a28",
  "email": "[email protected]",
  "name": "Alice Smith",
  "email_verified": true,

  "https://atlas.turing.com/org_id": "4047160a-abb2-497c-bf0c-3f4ab7cb0b16",
  "https://atlas.turing.com/org_name": "Turing",

  "https://atlas.turing.com/team_id": "ab2785b2-b5d0-4926-92fb-00aae5ec860a",
  "https://atlas.turing.com/team_name": "Engineering",

  "https://atlas.turing.com/project_id": "5ac942ba-0290-48a7-be6e-7ea58cd40b68",
  "https://atlas.turing.com/project_name": "LLM API",

  "https://atlas.turing.com/global_role": "member",
  "https://atlas.turing.com/team_role": "team_admin",
  "https://atlas.turing.com/project_role": "editor",

  "https://atlas.turing.com/permissions": [
    "read:org",
    "read:team",
    "write:team",
    "manage:team_users",
    "read:project",
    "write:project",
    "execute:services",
    "read:api_keys",
    "write:api_keys"
  ],

  "iat": 1766232057,
  "exp": 1766318457,
  "token_type": "access"
}

Token Expiration

Token Type	Expiration	Use Case
Access Token	24 hours	API requests
Refresh Token	30 days	Get new access token

---

Admin Dashboard Features

Access user management at: /admin/users

User List View

Column	Description
Name	User's display name
Email	User's email address
Global Role	super_admin, org_admin, or member
Status	active, invited, suspended, disabled
Teams	Number of team memberships
Last Login	Last login timestamp

User Actions

Action	Description
Invite User	Send invitation to new user
Edit User	Change global role, status
View Memberships	See user's teams and projects
Suspend User	Temporarily disable access
Assign to Team	Add user to a team

---

Common Scenarios

Scenario 1: Inviting a New User

1. Go to Admin → Users → Invite User
2. Enter email address (must be @turing.com)
3. Select team to add them to
4. Select team role (team_admin or team_member)
5. Optionally select projects and project roles
6. Click "Invite"

User receives invitation and can login immediately.
On first login, status changes from "invited" to "active".

Scenario 2: Promoting User to Org Admin

1. Go to Admin → Users → Find User
2. Click "Edit"
3. Change Global Role from "member" to "org_admin"
4. Save

User now has organization-wide access.
User should re-login to get updated JWT.

Scenario 3: Suspending a User

1. Go to Admin → Users → Find User
2. Click "Edit"
3. Change Status to "suspended"
4. Save

User cannot login anymore.
Existing sessions continue until JWT expires (max 24h).
Consider revoking their API keys separately.

Scenario 4: User Leaves the Organization

1. Change user status to "disabled"
2. Remove from all teams (cascades to projects)
3. Revoke any API keys they created
4. Document the offboarding

User is completely locked out.

---

Best Practices

Role Assignment

Practice	Reason
Start with member	Add privileges as needed
Few org_admins	2-3 per organization
Very few super_admins	Platform team only
Use team/project roles	More granular than global

Security

Practice	Reason
Prompt offboarding	Suspend immediately when employees leave
Regular audits	Review user list quarterly
Monitor failed logins	Detect suspicious activity
Review org_admin grants	Ensure they're still needed

---

Troubleshooting

"Account is suspended"

Error: 403 Forbidden: Account is suspended. Please contact administrator.

Cause: User status is suspended or disabled.

Solution: Admin must change status to active in User Management.

"You are not authorized"

Error: 403 Forbidden: You are not authorized to access this resource

Cause: User doesn't exist in the system or isn't invited.

Solution: Admin must invite the user first.

"Insufficient permissions"

Error: 403 Forbidden: Insufficient permissions

Cause: User's effective role doesn't have the required permission.

Solution:

1. Check what permission is needed

2. Assign appropriate role at team or project level

3. Or elevate global role if appropriate

"Invalid or expired token"

Error: 401 Unauthorized: Invalid or expired token

Cause: JWT has expired or is malformed.

Solution: User should re-login to get a fresh token.