Quickstart: Stack Auth

Integrate GL IAM with Stack Auth for modern, managed authentication.

When to use Stack Auth: Choose Stack Auth when you want managed authentication with minimal infrastructure, modern UI components, or need features like social login and MFA out of the box.

What you'll build: A FastAPI application that authenticates users via Stack Auth tokens and enforces role-based access control using GL IAM's unified interface.

Prerequisites

This example requires completion of all setup steps listed on the Prerequisites page. To summarize:

• Python 3.11+

• Access to the GDP Labs' Gen AI SDK repository (request via form or [e-mail])

• gcloud CLI: Install, then run gcloud auth login

• uv — Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

• A Stack Auth project (cloud or self-hosted)

• Stack Auth API keys (Project ID, Publishable Key, Secret Server Key)

Setup Stack Auth

Stack Auth Cloud

1. Go to Stack Auth Dashboard

2. Create a new project

3. Note your credentials:

   • Project ID (e.g., your-project-id)

   • Publishable Client Key (e.g., pck_...)

   • Secret Server Key (e.g., ssk_...)

Self-Hosted

Installation

Install GL IAM from the internal Google Artifact Registry (latest version).

Linux, macOS, or Windows WSL

uv init --bare
uv add --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" "gl-iam[fastapi,stackauth]"
uv add python-dotenv uvicorn

Windows PowerShell

Windows Command Prompt

5-Line Core

The essential code to validate Stack Auth tokens with GL IAM:

from gl_iam import IAMGateway
from gl_iam.providers.stackauth import StackAuthProvider, StackAuthConfig

config = StackAuthConfig(base_url="...", project_id="...", publishable_client_key="...", secret_server_key="...")
provider = StackAuthProvider(config)
gateway = IAMGateway.from_fullstack_provider(provider)

Step-by-Step

1

Configure Environment

Create .env file:

# For Stack Auth Cloud
STACKAUTH_BASE_URL=https://api.stack-auth.com
STACKAUTH_PROJECT_ID=your-project-id
STACKAUTH_PUBLISHABLE_CLIENT_KEY=pck_your_key
STACKAUTH_SECRET_SERVER_KEY=ssk_your_key

# For Self-Hosted (development)
# STACKAUTH_BASE_URL=http://localhost:8102
# STACKAUTH_PROJECT_ID=internal
# STACKAUTH_PUBLISHABLE_CLIENT_KEY=this-publishable-client-key-is-for-local-development-only
# STACKAUTH_SECRET_SERVER_KEY=this-secret-server-key-is-for-local-development-only

2

Setup Provider

import os
from contextlib import asynccontextmanager
from dotenv import load_dotenv
from fastapi import FastAPI

from gl_iam import IAMGateway
from gl_iam.fastapi import set_iam_gateway
from gl_iam.providers.stackauth import StackAuthConfig, StackAuthProvider

load_dotenv()

@asynccontextmanager
async def lifespan(app: FastAPI):
    config = StackAuthConfig(
        base_url=os.getenv("STACKAUTH_BASE_URL"),
        project_id=os.getenv("STACKAUTH_PROJECT_ID"),
        publishable_client_key=os.getenv("STACKAUTH_PUBLISHABLE_CLIENT_KEY"),
        secret_server_key=os.getenv("STACKAUTH_SECRET_SERVER_KEY"),
    )
    provider = StackAuthProvider(config)
    gateway = IAMGateway.from_fullstack_provider(provider)

    set_iam_gateway(gateway, default_organization_id=os.getenv("STACKAUTH_PROJECT_ID"))
    yield
    await provider.close()

app = FastAPI(title="GL-IAM Stack Auth Demo", lifespan=lifespan)

3

Add Protected Endpoints

from fastapi import Depends
from gl_iam import User
from gl_iam.fastapi import get_current_user, require_org_admin, require_org_member

@app.get("/health")
async def health():
    return {"status": "healthy", "provider": "stackauth"}

@app.get("/me")
async def get_me(user: User = Depends(get_current_user)):
    return {"id": user.id, "email": user.email, "roles": user.roles}

@app.get("/member-area")
async def member_area(
    user: User = Depends(get_current_user),
    _: None = Depends(require_org_member()),
):
    return {"message": f"Welcome {user.email}!", "access_level": "member"}

@app.get("/admin-area")
async def admin_area(
    user: User = Depends(get_current_user),
    _: None = Depends(require_org_admin()),
):
    return {"message": f"Welcome Admin {user.email}!", "access_level": "admin"}

4

Run the Server

uv run uvicorn main:app --reload

Output:

INFO:     Uvicorn running on http://127.0.0.1:8000

5

Test the API

# Get your Stack Auth token (from frontend SDK or dashboard)
TOKEN="your-stack-auth-access-token"

# Health check
curl http://localhost:8000/health

# Get user profile
curl http://localhost:8000/me -H "Authorization: Bearer $TOKEN"

# Access member area
curl http://localhost:8000/member-area -H "Authorization: Bearer $TOKEN"

# Access admin area (requires team_admin permission)
curl http://localhost:8000/admin-area -H "Authorization: Bearer $TOKEN"

Congratulations! You've integrated GL IAM with Stack Auth.

Complete Example

Create main.py:

"""Secure FastAPI application with GL-IAM Stack Auth authentication."""

import os
from contextlib import asynccontextmanager

from dotenv import load_dotenv
from fastapi import Depends, FastAPI
from pydantic import BaseModel

from gl_iam import IAMGateway, User
from gl_iam.fastapi import (
    get_current_user,
    require_org_admin,
    require_org_member,
    set_iam_gateway,
)
from gl_iam.providers.stackauth import StackAuthConfig, StackAuthProvider

load_dotenv()


@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize GL-IAM with Stack Auth provider."""
    config = StackAuthConfig(
        base_url=os.getenv("STACKAUTH_BASE_URL", "http://localhost:8102"),
        project_id=os.getenv("STACKAUTH_PROJECT_ID"),
        publishable_client_key=os.getenv("STACKAUTH_PUBLISHABLE_CLIENT_KEY"),
        secret_server_key=os.getenv("STACKAUTH_SECRET_SERVER_KEY"),
    )
    provider = StackAuthProvider(config)
    gateway = IAMGateway.from_fullstack_provider(provider)

    set_iam_gateway(gateway, default_organization_id=os.getenv("STACKAUTH_PROJECT_ID"))

    # Verify connection
    is_healthy = await provider.health_check()
    if is_healthy:
        print(f"Connected to Stack Auth at {os.getenv('STACKAUTH_BASE_URL')}")

    yield
    await provider.close()


app = FastAPI(title="GL-IAM Stack Auth Demo", lifespan=lifespan)


class UserResponse(BaseModel):
    """Response model for user data."""
    id: str
    email: str
    display_name: str | None
    roles: list[str]


@app.get("/health")
async def health():
    """Public health check endpoint."""
    return {"status": "healthy", "provider": "stackauth"}


@app.get("/me", response_model=UserResponse)
async def get_me(user: User = Depends(get_current_user)):
    """Get current user profile. Requires authentication."""
    return UserResponse(
        id=user.id,
        email=user.email,
        display_name=user.display_name,
        roles=user.roles,
    )


@app.get("/member-area")
async def member_area(
    user: User = Depends(get_current_user),
    _: None = Depends(require_org_member()),
):
    """Member area. Requires ORG_MEMBER, ORG_ADMIN, or PLATFORM_ADMIN."""
    return {"message": f"Welcome {user.email}!", "access_level": "member"}


@app.get("/admin-area")
async def admin_area(
    user: User = Depends(get_current_user),
    _: None = Depends(require_org_admin()),
):
    """Admin area. Requires ORG_ADMIN or PLATFORM_ADMIN."""
    return {"message": f"Welcome Admin {user.email}!", "access_level": "admin"}


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Run it:

uv run main.py

Getting Access Tokens

Stack Auth tokens are typically obtained through the frontend SDK:

React/Next.js

import { useUser } from "@stackframe/stack";

function MyComponent() {
  const user = useUser();

  async function callAPI() {
    const token = await user.getAuthJson();
    const response = await fetch("http://localhost:8000/me", {
      headers: { Authorization: `Bearer ${token.accessToken}` }
    });
    return response.json();
  }
}

Dashboard

Stack Auth Role Mapping

Stack Auth team permissions map to GL IAM standard roles:

Stack Auth Permission	GL IAM Standard Role	Access Level
team_admin	ORG_ADMIN	Admin endpoints
team_member	ORG_MEMBER	Member endpoints

Important: Users must have a selected team in Stack Auth for roles to work. The user's active team context determines their permissions.

Common Pitfalls

Pitfall	Solution
Token validation fails	Ensure secret_server_key is set correctly
User has no roles	User must be added to a team with permissions assigned
Wrong base URL	Use https://api.stack-auth.com for cloud, http://localhost:8102 for self-hosted
CORS issues in frontend	Configure allowed origins in Stack Auth dashboard