Feat: User Invitation flow

.env.example

@@ -84,3 +84,12 @@ OPENAI_API_KEY=""
 
 KAAPI_GUARDRAILS_AUTH=""
 KAAPI_GUARDRAILS_URL=""
+
+SMTP_HOST=
+SMTP_PORT=
+SMTP_TLS=True
+SMTP_USER=
+SMTP_PASSWORD=
+EMAILS_FROM_EMAIL=
+EMAILS_FROM_NAME=Kaapi
+FRONTEND_HOST=

backend/app/api/docs/auth/invite_verify.md

@@ -0,0 +1,20 @@
+# Verify Invitation
+
+Verify an invitation token from a magic link email and log the user in.
+
+## Query Parameters
+
+- **token** (required): The invitation JWT token from the email link.
+
+## Behavior
+
+1. Validates the invitation token (checks signature, expiry, and type).
+2. Looks up the user by the email embedded in the token.
+3. If the user exists and is inactive (first login), activates the account.
+4. Returns a JWT access token with the org/project from the invitation embedded.
+5. Sets `access_token` and `refresh_token` as HTTP-only cookies.
+
+## Error Responses
+
+- **400**: Invalid or expired invitation link.
+- **404**: User account not found.

backend/app/api/routes/auth.py

@@ -21,6 +21,7 @@
     build_token_response,
     clear_auth_cookies,
     validate_refresh_token,
+    verify_invite_token,
 )
 from app.utils import APIResponse, load_description
 
@@ -198,3 +199,47 @@ def logout() -> JSONResponse:
     response = JSONResponse(content=api_response.model_dump())
     clear_auth_cookies(response)
     return response
+
+
+@router.get(
+    "/invite/verify",
+    description=load_description("auth/invite_verify.md"),
+    response_model=APIResponse[Token],
+)
+def verify_invitation(session: SessionDep, token: str) -> JSONResponse:
+    """Verify an invitation token, activate the user, and log them in."""
+
+    invite_data = verify_invite_token(token)
+    if not invite_data:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid or expired invitation link",
+        )
+
+    user = get_user_by_email(session=session, email=invite_data["email"])
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User account not found. Please contact support.",
+        )
+
+    # Activate user if not already active
+    if not user.is_active:
+        user.is_active = True
+        session.add(user)
+        session.commit()
+        session.refresh(user)
+        logger.info(
+            f"[verify_invitation] User activated via invite | user_id: {user.id}"
+        )
+
+    response = build_token_response(
+        user_id=user.id,
+        organization_id=invite_data["organization_id"],
+        project_id=invite_data["project_id"],
+    )
+
+    logger.info(
+        f"[verify_invitation] Invitation verified | user_id: {user.id}, project_id: {invite_data['project_id']}"
+    )
+    return response

backend/app/api/routes/user_project.py

@@ -5,6 +5,9 @@
 
 from app.api.deps import AuthContextDep, SessionDep
 from app.api.permissions import Permission, require_permission
+from app.core.config import settings
+from app.crud.organization import get_organization_by_id
+from app.crud.project import get_project_by_id
 from app.crud.user_project import (
     add_user_to_project,
     get_users_by_project,
@@ -15,7 +18,13 @@
     Message,
     UserProjectPublic,
 )
-from app.utils import APIResponse, load_description
+from app.services.auth import generate_invite_token
+from app.utils import (
+    APIResponse,
+    generate_invite_email,
+    load_description,
+    send_email,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -83,6 +92,37 @@ def add_project_users(
 
     session.commit()
 
+    # Send invitation emails
+    organization = get_organization_by_id(session=session, org_id=body.organization_id)
+    project = get_project_by_id(session=session, project_id=body.project_id)
+
+    if settings.emails_enabled and organization and project:
+        for entry in body.users:
+            try:
+                invite_token = generate_invite_token(
+                    email=str(entry.email),
+                    organization_id=body.organization_id,
+                    project_id=body.project_id,
+                )
+                email_data = generate_invite_email(
+                    email_to=str(entry.email),
+                    project_name=project.name,
+                    organization_name=organization.name,
+                    invite_token=invite_token,
+                )
+                send_email(
+                    email_to=str(entry.email),
+                    subject=email_data.subject,
+                    html_content=email_data.html_content,
+                )
+                logger.info(
+                    f"[add_project_users] Invitation email sent | email: {entry.email}"
+                )
+            except Exception as e:
+                logger.error(
+                    f"[add_project_users] Failed to send invitation email | email: {entry.email}, error: {e}"
+                )
+
     # Re-fetch all users for this project to return the full list
     results = get_users_by_project(session=session, project_id=body.project_id)
 

backend/app/core/config.py

@@ -57,6 +57,27 @@ class Settings(BaseSettings):
     # Google OAuth
     GOOGLE_CLIENT_ID: str = ""
 
+    # Frontend URL for magic links
+    FRONTEND_HOST: str = "http://localhost:3000"
+
+    # Invitation token expiry (default 7 days)
+    INVITE_TOKEN_EXPIRE_HOURS: int = 24 * 7
+
+    # SMTP / Email
+    SMTP_HOST: str = ""
+    SMTP_PORT: int = 587
+    SMTP_USER: str = ""
+    SMTP_PASSWORD: str = ""
+    SMTP_TLS: bool = True
+    SMTP_SSL: bool = False
+    EMAILS_FROM_EMAIL: str = ""
+    EMAILS_FROM_NAME: str = ""
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def emails_enabled(self) -> bool:
+        return bool(self.SMTP_HOST and self.EMAILS_FROM_EMAIL)
+
     @computed_field  # type: ignore[prop-decorator]
     @property
     def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn:

backend/app/email-templates/build/invite_user.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>You're invited to {{ project_name }}</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; background-color: #f4f4f5;">
+  <table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0">
+    <tr>
+      <td style="padding: 60px 20px;">
+        <table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0" style="max-width: 520px; margin: 0 auto;">
+          <tr>
+            <td align="center" style="background-color: #ffffff; padding: 48px 40px; text-align: center;">
+              <h1 style="margin: 0 0 4px; font-size: 22px; font-weight: 600; color: #18181b;">
+                Kaapi Konsole
+              </h1>
+              <p style="margin: 0 0 20px; font-size: 14px; color: #a1a1aa;">
+                {{ organization_name }}
+              </p>
+              <table role="presentation" width="40" cellspacing="0" cellpadding="0" border="0" style="margin: 0 auto 20px;">
+                <tr>
+                  <td style="border-top: 2px solid #e4e4e7;"></td>
+                </tr>
+              </table>
+              <p style="margin: 0 0 5px; font-size: 15px; line-height: 1.7; color: #3f3f46;">
+                You have been invited to join the <strong>{{ project_name }}</strong> project on {{ app_name }}.
+              </p>
+              <p style="margin: 0 0 20px; font-size: 15px; line-height: 1.7; color: #3f3f46;">
+                Click the button below to accept the invitation and get started.
+              </p>
+              <table role="presentation" cellspacing="0" cellpadding="0" border="0" style="margin: 0 auto;">
+                <tr>
+                  <td align="center" style="background-color: #2563eb; border-radius: 10px;">
+                    <a href="{{ link }}" target="_blank" style="display: inline-block; padding: 10px 30px; font-size: 15px; font-weight: 600; color: #ffffff; text-decoration: none;">
+                      Accept Invitation
+                    </a>
+                  </td>
+                </tr>
+              </table>
+              <p style="margin: 20px 0 0; font-size: 12px; color: #a1a1aa; line-height: 1.6;">
+                This invitation expires in {{ valid_days }} days.<br>
+                If you did not expect this invitation, you can safely ignore this email.
+              </p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>

backend/app/services/auth.py

@@ -1,5 +1,5 @@
 import logging
-from datetime import timedelta
+from datetime import datetime, timedelta, timezone
 
 import jwt as pyjwt
 from fastapi import HTTPException, status
@@ -176,3 +176,44 @@ def validate_refresh_token(
         raise HTTPException(status_code=403, detail="Inactive user")
 
     return user, token_data
+
+
+def generate_invite_token(
+    email: str,
+    organization_id: int,
+    project_id: int,
+) -> str:
+    """Generate a JWT invitation token for a user."""
+    delta = timedelta(hours=settings.INVITE_TOKEN_EXPIRE_HOURS)
+    now = datetime.now(timezone.utc)
+    expires = now + delta
+    to_encode = {
+        "exp": expires.timestamp(),
+        "nbf": now,
+        "sub": email,
+        "org_id": organization_id,
+        "project_id": project_id,
+        "type": "invite",
+    }
+    return pyjwt.encode(to_encode, settings.SECRET_KEY, algorithm=security.ALGORITHM)
+
+
+def verify_invite_token(token: str) -> dict | None:
+    """
+    Verify an invitation token and return the payload.
+
+    Returns dict with email, org_id, project_id or None if invalid.
+    """
+    try:
+        payload = pyjwt.decode(
+            token, settings.SECRET_KEY, algorithms=[security.ALGORITHM]
+        )
+        if payload.get("type") != "invite":
+            return None
+        return {
+            "email": payload["sub"],
+            "organization_id": payload["org_id"],
+            "project_id": payload["project_id"],
+        }
+    except (InvalidTokenError, KeyError):
+        return None

backend/app/tests/api/test_auth.py

@@ -6,13 +6,18 @@
 
 from app.core.config import settings
 from app.core.security import create_access_token, create_refresh_token
+from app.services.auth import (
+    generate_invite_token,
+    verify_invite_token,
+)
 from app.tests.utils.auth import TestAuthContext
 from app.tests.utils.user import create_random_user
 
 GOOGLE_AUTH_URL = f"{settings.API_V1_STR}/auth/google"
 SELECT_PROJECT_URL = f"{settings.API_V1_STR}/auth/select-project"
 REFRESH_URL = f"{settings.API_V1_STR}/auth/refresh"
 LOGOUT_URL = f"{settings.API_V1_STR}/auth/logout"
+INVITE_VERIFY_URL = f"{settings.API_V1_STR}/auth/invite/verify"
 
 MOCK_GOOGLE_PROFILE = {
     "email": None,  # set per test
@@ -107,9 +112,6 @@ def test_google_auth_activates_inactive_user(
         resp = client.post(GOOGLE_AUTH_URL, json={"token": "fake"})
         assert resp.status_code == 200
 
-        db.refresh(user)
-        assert user.is_active is True
-
     @patch("app.api.routes.auth.id_token.verify_oauth2_token")
     @patch("app.api.routes.auth.settings")
     def test_google_auth_success_no_projects(
@@ -298,3 +300,75 @@ def test_logout_success(self, client: TestClient):
         body = resp.json()
         assert body["success"] is True
         assert body["data"]["message"] == "Logged out successfully"
+
+
+class TestInviteVerify:
+    """Test suite for GET /auth/invite/verify endpoint."""
+
+    def test_verify_invalid_token(self, client: TestClient):
+        """Test returns 400 for invalid invite token."""
+        resp = client.get(f"{INVITE_VERIFY_URL}?token=invalid.token")
+        assert resp.status_code == 400
+
+    def test_verify_user_not_found(self, client: TestClient):
+        """Test returns 404 when invited user doesn't exist."""
+        token = generate_invite_token(
+            email="ghost@example.com", organization_id=1, project_id=1
+        )
+        resp = client.get(f"{INVITE_VERIFY_URL}?token={token}")
+        assert resp.status_code == 404
+
+    def test_verify_activates_inactive_user(
+        self, db: Session, client: TestClient, user_api_key: TestAuthContext
+    ):
+        """Test invite verification activates inactive user."""
+        user = create_random_user(db)
+        user.is_active = False
+        db.add(user)
+        db.commit()
+        db.refresh(user)
+
+        token = generate_invite_token(
+            email=user.email,
+            organization_id=user_api_key.organization.id,
+            project_id=user_api_key.project.id,
+        )
+        resp = client.get(f"{INVITE_VERIFY_URL}?token={token}")
+        assert resp.status_code == 200
+
+        db.refresh(user)
+        assert user.is_active is True
+        assert "access_token" in resp.json()["data"]
+
+    def test_verify_success_active_user(
+        self, db: Session, client: TestClient, user_api_key: TestAuthContext
+    ):
+        """Test invite verification works for already active user."""
+        user = create_random_user(db)
+        token = generate_invite_token(
+            email=user.email,
+            organization_id=user_api_key.organization.id,
+            project_id=user_api_key.project.id,
+        )
+        resp = client.get(f"{INVITE_VERIFY_URL}?token={token}")
+        assert resp.status_code == 200
+        assert "access_token" in resp.json()["data"]
+
+
+class TestTokenGeneration:
+    """Test suite for services/auth.py token generation functions."""
+
+    def test_generate_and_verify_invite_token(self):
+        """Test invite token roundtrip."""
+        token = generate_invite_token(
+            email="test@example.com", organization_id=1, project_id=2
+        )
+        result = verify_invite_token(token)
+        assert result is not None
+        assert result["email"] == "test@example.com"
+        assert result["organization_id"] == 1
+        assert result["project_id"] == 2
+
+    def test_verify_invite_token_invalid(self):
+        """Test invite verify returns None for garbage tokens."""
+        assert verify_invite_token("garbage") is None