# Introduction

**Enterprise-grade Authentication & Authorization Gateway for Atlas Microservices**

Atlas Auth Guard is a centralized authentication and authorization service that provides:

* 🔐 **Single Sign-On (SSO)** via Google OAuth
* 👥 **Multi-tenant architecture** with Organization → Team → Project hierarchy
* 🎭 **Role-based access control (RBAC)** with fine-grained permissions
* 🔑 **API key management** for service-to-service communication
* 🚦 **Service routing** to backend microservices with policy enforcement

***

## 🌐 Environment URLs

### Production Environment

| Service               | URL                                                                       | Description                                      |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |
| **Web Dashboard**     | <https://auth-gw.atlas.turing.com>                                        | Admin portal for managing teams, projects, users |
| **API Endpoint**      | <https://apac-atlas-guard-svc-589688574290.asia-south1.run.app>           | Backend API                                      |
| **API Documentation** | <https://apac-atlas-guard-svc-589688574290.asia-south1.run.app/v1/docs>   | Swagger UI with all endpoints                    |
| **Health Check**      | <https://apac-atlas-guard-svc-589688574290.asia-south1.run.app/v1/health> | Service health status                            |

### Development (R\&D) Environment

| Service               | URL                                                                       | Description               |
| --------------------- | ------------------------------------------------------------------------- | ------------------------- |
| **Web Dashboard**     | <https://auth-gw.rd.atlas.turing.com>                                     | Development admin portal  |
| **API Endpoint**      | <https://apac-atlas-guard-svc-264685500362.us-central1.run.app>           | Development API           |
| **API Documentation** | <https://apac-atlas-guard-svc-264685500362.us-central1.run.app/v1/docs>   | Development Swagger UI    |
| **Health Check**      | <https://apac-atlas-guard-svc-264685500362.us-central1.run.app/v1/health> | Development health status |

***

## 📚 Documentation Guide

### For End Users

| Document                                                   | Description                                     |
| ---------------------------------------------------------- | ----------------------------------------------- |
| [Getting Started](#getting-started)                        | Quick overview of how to use the system         |
| [Team Management](/core-features/team_management.md)       | Understanding teams, members, and team policies |
| [Project Management](/core-features/project_management.md) | Managing projects, metadata, and data isolation |
| [User Management](/core-features/user_management.md)       | User roles, permissions, and access control     |
| [API Keys](/core-features/api_keys.md)                     | Creating and managing API keys                  |

### For Developers

| Document                                                                                               | Description                                                 |
| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| [SSO Integration](/developer-guide/sso_integration.md)                                                 | Integrate SSO into your application                         |
| [Service Routes](/developer-guide/service_routes.md)                                                   | How Auth Guard routes requests to backends                  |
| [Service Policies](/developer-guide/service_policies.md)                                               | Service-to-service authorization                            |
| [Notifications Admin](/developer-guide/notifications_admin.md)                                         | Notification service admin UI behavior + required endpoints |
| [Security Model](/architecture/security_model.md)                                                      | Complete security architecture                              |
| [Troubleshooting](https://github.com/TuringGpt/apac-atlas-guard-svc/blob/main/docs/TROUBLESHOOTING.md) | Common issues and solutions                                 |

***

## 🏗️ System Architecture

### Multi-Tenant Hierarchy

Atlas Auth Guard implements a three-level tenant hierarchy:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                            ORGANIZATION                                      │
│                              (Turing)                                        │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │ • Billing entity                                                       │ │
│  │ • SSO/MFA policies                                                     │ │
│  │ • Organization-wide settings                                           │ │
│  │ • Users belong to organization via @turing.com email                   │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │       TEAM          │  │       TEAM          │  │       TEAM          │  │
│  │    Engineering      │  │    Data Science     │  │      Platform       │  │
│  │ ┌─────────────────┐ │  │ ┌─────────────────┐ │  │ ┌─────────────────┐ │  │
│  │ │ • Team admins   │ │  │ │ • Team admins   │ │  │ │ • Team admins   │ │  │
│  │ │ • Team members  │ │  │ │ • Team members  │ │  │ │ • Team members  │ │  │
│  │ │ • Service policy│ │  │ │ • Service policy│ │  │ │ • Service policy│ │  │
│  │ └─────────────────┘ │  │ └─────────────────┘ │  │ └─────────────────┘ │  │
│  │                     │  │                     │  │                     │  │
│  │ ┌───────┐ ┌───────┐ │  │ ┌───────┐          │  │ ┌───────┐          │  │
│  │ │Project│ │Project│ │  │ │Project│          │  │ │Project│          │  │
│  │ │LLM API│ │Rater  │ │  │ │Research│         │  │ │Guard  │          │  │
│  │ │       │ │       │ │  │ │       │          │  │ │       │          │  │
│  │ │API Key│ │API Key│ │  │ │API Key│          │  │ │API Key│          │  │
│  │ └───────┘ └───────┘ │  │ └───────┘          │  │ └───────┘          │  │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Key Concepts

| Concept          | Description                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Organization** | Top-level tenant. All users, teams, and projects belong to an organization. Currently: "Turing"                    |
| **Team**         | Logical grouping of users. Teams have service access policies that control which backend services members can use. |
| **Project**      | Isolated workspace within a team. Each project has its own API key and data isolation.                             |
| **User**         | Individual authenticated via Google OAuth. Users have roles at global, team, and project levels.                   |

***

## 👥 Role Hierarchy

Atlas Auth Guard implements a comprehensive role-based access control (RBAC) system:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           ROLE HIERARCHY                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  GLOBAL SCOPE (Platform-wide)                                               │
│  ════════════════════════════                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ super_admin (Level 100)                                              │   │
│  │ • Full platform access                                               │   │
│  │ • Can access all organizations (if multi-org)                        │   │
│  │ • Bypasses all access checks                                         │   │
│  │ • Can manage system routes and policies                              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ org_admin (Level 80)                                                 │   │
│  │ • Full organization access                                           │   │
│  │ • Can see all teams and projects in the org                          │   │
│  │ • Bypasses team policies and membership checks                       │   │
│  │ • Can manage routes and policies                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ member (Level 70)                                                    │   │
│  │ • Basic organization member                                          │   │
│  │ • Must be explicitly added to teams                                  │   │
│  │ • Subject to team policies                                           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  TEAM SCOPE                                                                 │
│  ══════════                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ team_admin (Level 60)                                                │   │
│  │ • Create/delete projects in the team                                 │   │
│  │ • Add/remove team members                                            │   │
│  │ • Manage team API keys                                               │   │
│  │ • Configure team service policy                                      │   │
│  │ • Has implicit access to all projects in the team                    │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ team_member (Level 50)                                               │   │
│  │ • View team information                                              │   │
│  │ • Access projects they're assigned to                                │   │
│  │ • Execute services allowed by team policy                            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  PROJECT SCOPE                                                              │
│  ═════════════                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ project_admin (Level 40)                                             │   │
│  │ • Manage project members                                             │   │
│  │ • Manage project settings and metadata                               │   │
│  │ • Create/revoke project API keys                                     │   │
│  │ • Full read/write access to project data                             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ editor (Level 20)                                                    │   │
│  │ • Read and write project data                                        │   │
│  │ • Execute services                                                   │   │
│  │ • Cannot manage members or settings                                  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ viewer (Level 10)                                                    │   │
│  │ • Read-only access to project data                                   │   │
│  │ • Cannot modify anything                                             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Effective Role Calculation

When you access a resource, your **effective role** is determined by the most specific assignment:

| Priority    | Check                  | Example                                                                         |
| ----------- | ---------------------- | ------------------------------------------------------------------------------- |
| 1️⃣ Highest | Explicit project role  | You have `viewer` on Project X → You're a viewer                                |
| 2️⃣         | Explicit team role     | You have `team_admin` on Team A → You're team\_admin for all projects in Team A |
| 3️⃣ Lowest  | Global role (fallback) | You're `org_admin` globally → Full org access where no explicit role exists     |

**Important:** Even `super_admin` can be restricted to `viewer` on a specific project if explicitly assigned.

***

## 🚀 Getting Started

### For Dashboard Users

1. **Login**: Go to <https://auth-gw.atlas.turing.com> and click "Sign in with Google"
2. **Select Context**: Choose your team and project from the dropdown
3. **Navigate**: Use the sidebar to access Teams, Projects, Users, API Keys, etc.

### For Developers Integrating SSO

```javascript
// Minimal SSO integration - 10 lines of code
const AUTH_URL = 'https://auth-gw.atlas.turing.com';

function login() {
  // Open SSO popup
  const popup = window.open(
    `${AUTH_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`,
    'Atlas SSO',
    'width=500,height=600'
  );

  // Listen for auth result
  window.addEventListener('message', (event) => {
    if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
      const { token, user } = event.data;
      localStorage.setItem('auth_token', token);
      console.log('Logged in as:', user.user_name);
      console.log('Team:', user.team_name);
      console.log('Project:', user.project_name);
    }
  });
}
```

See [SSO Integration Guide](/developer-guide/sso_integration.md) for complete documentation.

### For Backend Services Using API Keys

```python
import httpx

AUTH_GUARD_URL = "https://auth-gw.atlas.turing.com"
API_KEY = "sk-your-project-api-key"

async def call_llm_service(prompt: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{AUTH_GUARD_URL}/v1/llm/generate",
            headers={
                "X-Atlas-API-Key": API_KEY,
                "Content-Type": "application/json"
            },
            json={"prompt": prompt}
        )
        return response.json()
```

See [API Keys Guide](/core-features/api_keys.md) for complete documentation.

***

## 🔄 Request Flow

Here's how a request flows through the system:

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                              REQUEST FLOW                                     │
└──────────────────────────────────────────────────────────────────────────────┘

  ┌─────────┐
  │  User   │
  │ Browser │
  └────┬────┘
       │
       │ 1. Request with JWT token
       │    Authorization: Bearer eyJhbG...
       ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │                          AUTH GUARD                                      │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 2. AUTHENTICATION                                                   │ │
  │  │    • Validate JWT signature                                         │ │
  │  │    • Check token expiration                                         │ │
  │  │    • Verify user is active                                          │ │
  │  │    ❌ If fails → 401 Unauthorized                                    │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 3. TEAM POLICY CHECK                                                │ │
  │  │    • Is the target service in team's allowed_services?              │ │
  │  │    • Bypassed for: super_admin, org_admin                           │ │
  │  │    ❌ If fails → 403 Forbidden: Service not allowed                  │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 4. MEMBERSHIP CHECK                                                 │ │
  │  │    • Is user a member of the team in their JWT?                     │ │
  │  │    • Is user a member of the project (if project_id in JWT)?        │ │
  │  │    • Bypassed for: super_admin, org_admin                           │ │
  │  │    ❌ If fails → 403 Forbidden: Not a member                         │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 5. INJECT HEADERS                                                   │ │
  │  │    • X-User-ID, X-User-Email, X-User-Name                           │ │
  │  │    • X-Org-ID, X-Team-ID, X-Project-ID                              │ │
  │  │    • X-Effective-Role, X-Permissions                                │ │
  │  │    • X-Request-ID (for tracing)                                     │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 6. PROXY TO BACKEND                                                 │ │
  │  │    • Route: /v1/llm/generate → https://llm-svc.run.app/api/v1/...   │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  └─────────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
                          ┌─────────────┐
                          │   Backend   │
                          │   Service   │
                          │             │
                          │ Receives:   │
                          │ • Headers   │
                          │ • Request   │
                          └─────────────┘
```

***

## 📞 Support

* **API Documentation**: See Swagger UI links above
* **Issues**: Contact <atlas-support@turing.com>
* **Feature Requests**: Create a ticket in JIRA

***

**Built with ❤️ by the Turing APAC Platform Team**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gw-docs.atlas.turing.com/getting-started/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.