Custom Scope Mappings

This example demonstrates how to define custom scope mappings for your AgentOS endpoints, allowing you to create your own permission structure.

1. Create a Python file

   custom_scope_mappings.py

   import os
   from datetime import UTC, datetime, timedelta
   
   import jwt
   from agno.agent import Agent
   from agno.db.postgres import PostgresDb
   from agno.models.openai import OpenAIResponses
   from agno.os import AgentOS
   from agno.os.middleware import JWTMiddleware
   from agno.tools.hackernews import HackerNewsTools
   
   JWT_SECRET = os.getenv("JWT_VERIFICATION_KEY", "your-secret-key-at-least-256-bits-long")
   
   db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")
   
   research_agent = Agent(
       id="research-agent",
       name="Research Agent",
       model=OpenAIResponses(id="gpt-5.2"),
       db=db,
       tools=[HackerNewsTools()],
       markdown=True,
   )
   
   # Define custom scope mappings
   # Format: "METHOD /path": ["scope1", "scope2"]
   custom_scopes = {
       # Override default agent scopes with custom ones
       "GET /agents": ["app:read"],
       "GET /agents/*": ["app:read"],
       "POST /agents/*/runs": ["app:run", "app:execute"],  # Require BOTH scopes
       
       # Session endpoints - only admins can view
       "GET /sessions": ["app:admin"],
       "GET /sessions/*": ["app:read", "sessions:read"],
       
       # Memory endpoints with custom scopes
       "GET /memories": ["memory:admin"],
       "POST /memories": ["memory:write"],
       
       # Config endpoint - system admins only
       "GET /config": ["app:admin"],
   }
   
   # Create AgentOS without built-in authorization
   agent_os = AgentOS(
       id="my-agent-os",
       description="Custom Scope Mappings AgentOS",
       agents=[research_agent],
   )
   
   app = agent_os.get_app()
   
   # Add JWT middleware with custom scope mappings
   app.add_middleware(
       JWTMiddleware,
       verification_keys=[JWT_SECRET],
       algorithm="HS256",
       scope_mappings=custom_scopes,  # Custom scopes enable RBAC automatically
       admin_scope="app:superadmin",  # Custom admin scope
   )
   
   
   if __name__ == "__main__":
       # Basic user - can only read
       basic_user_token = jwt.encode(
           {
               "sub": "user_123",
               "scopes": ["app:read"],
               "exp": datetime.now(UTC) + timedelta(hours=24),
           },
           JWT_SECRET,
           algorithm="HS256",
       )
   
       # Power user - can read and execute
       power_user_token = jwt.encode(
           {
               "sub": "user_456",
               "scopes": ["app:read", "app:run", "app:execute"],
               "exp": datetime.now(UTC) + timedelta(hours=24),
           },
           JWT_SECRET,
           algorithm="HS256",
       )
   
       # Admin user - has admin scope
       admin_token = jwt.encode(
           {
               "sub": "admin_789",
               "scopes": ["app:admin", "app:read", "app:run", "app:execute"],
               "exp": datetime.now(UTC) + timedelta(hours=24),
           },
           JWT_SECRET,
           algorithm="HS256",
       )
   
       # Super admin - bypasses all checks
       superadmin_token = jwt.encode(
           {
               "sub": "superadmin",
               "scopes": ["app:superadmin"],
               "exp": datetime.now(UTC) + timedelta(hours=24),
           },
           JWT_SECRET,
           algorithm="HS256",
       )
   
       print("Basic User (app:read only):")
       print(basic_user_token)
       print("\nPower User (app:read, app:run, app:execute):")
       print(power_user_token)
       print("\nAdmin (app:admin + all permissions):")
       print(admin_token)
       print("\nSuper Admin (app:superadmin - bypasses all):")
       print(superadmin_token)
   
       agent_os.serve(app="custom_scope_mappings:app", port=7777, reload=True)
   
2. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
3. Install dependencies

   uv pip install -U agno openai pyjwt "fastapi[standard]" uvicorn sqlalchemy pgvector psycopg
   
4. Export your OpenAI API key

   Mac/Linux

   export OPENAI_API_KEY="your_openai_api_key_here"
   

   $Env:OPENAI_API_KEY="your_openai_api_key_here"
   
5. Setup PostgreSQL Database

   docker run -d \
     --name agno-postgres \
     -e POSTGRES_DB=ai \
     -e POSTGRES_USER=ai \
     -e POSTGRES_PASSWORD=ai \
     -p 5532:5432 \
     pgvector/pgvector:pg17
   
6. Run the AgentOS

   python custom_scope_mappings.py
   
7. Test Custom Scopes

   # Basic user can read agents
   export BASIC_TOKEN="<basic_user_token>"
   curl -H "Authorization: Bearer $BASIC_TOKEN" http://localhost:7777/agents
   
   # Basic user cannot run agents (missing app:run and app:execute)
   curl -X POST -H "Authorization: Bearer $BASIC_TOKEN" \
     -F "message=test" http://localhost:7777/agents/research-agent/runs
   
   # Power user can run agents
   export POWER_TOKEN="<power_user_token>"
   curl -X POST -H "Authorization: Bearer $POWER_TOKEN" \
     -F "message=Search for news" \
     http://localhost:7777/agents/research-agent/runs
   
   # Only admin can view sessions
   export ADMIN_TOKEN="<admin_token>"
   curl -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:7777/sessions