​

OAuth Scope Migration - Three-Tier Model

​

Summary

​

New Scope Model

​

Three Scopes

1. api:read - Read-only access to all resources
   • List operations (campaigns, creatives, brand agents, etc.)
   • Get operations (retrieve specific resources)
   • Analytics and reporting
   • Product discovery
2. api:manage - Create, update, delete resources
   • Campaign management
   • Creative operations
   • Brand agent management
   • Brand stories and standards
   • Tactics and media buys
   • Signal management
3. api:admin - Administrative operations
   • Sales agent registration/management
   • Signals agent registration/management
   • Webhook registration
   • System-level configuration

​

WorkOS Configuration Required

1. Resource Server: https://api.agentic.scope3.com/mcp
2. Scopes to Add:
   Copy

   Ask AI

   api:read - Read-only access to all campaign and creative resources
   api:manage - Create, update, and delete campaigns, creatives, and related resources
   api:admin - Administrative access for agent registration and webhooks
   

3. Discovery Endpoint: Ensure https://identity.scope3.com/.well-known/openid-configuration includes these scopes in scopes_supported

​

Code Changes Made

​

Files Modified

1. src/auth/mcp-auth-config.ts
   • Replaced TOOL_SCOPES with simplified three-tier model
   • Updated getAllScopes() to return only three scopes
   • Remapped all tools in TOOL_SCOPE_MAPPING to new scopes
2. src/__tests__/auth/mcp-auth-dual.test.ts
   • Updated tests to validate three-tier model
   • Changed scope assertions to match new model
   • All tests passing ✅

​

Tool Scope Assignments

• List operations: campaigns_list, creatives_list, brand_agents_list, etc.
• Get operations: campaigns_get_summary, creatives_get, brand_agents_get, etc.
• Analytics: assets_analytics, metrics_show_agentic, reporting_export_data
• Discovery: products_list, sales_agents_list, signals_list_custom

• Create operations: campaigns_create, creatives_create, brand_agents_create
• Update operations: campaigns_update, creatives_update, tactics_update
• Delete operations: campaigns_delete, creatives_delete, media_buys_delete
• Assignments: creatives_assign, creatives_unassign, signals_activate

• Agent registration: sales_agents_register, signals_agents_register
• Agent management: sales_agents_update, signals_agents_update
• Unregistration: sales_agents_unregister, signals_agents_unregister
• Webhooks: webhooks_register

​

Migration Benefits

1. Simplicity: 3 scopes vs 65+ - much easier to reason about
2. Standards-compliant: Follows common OAuth patterns (read/write/admin)
3. Easier client integration: Simple permission model for API consumers
4. Future-proof: Room to add finer-grained scopes later if needed
5. Backward compatible: API key auth still grants all scopes

​

Testing

✓ 14 tests passed in src/__tests__/auth/mcp-auth-dual.test.ts

• Three-tier scope model
• Tool scope mappings
• API key authentication (grants all scopes)
• Scope validation logic

​

Next Steps

1. ✅ Code updated and tested
2. ⏳ Configure WorkOS with three scopes
3. ⏳ Verify OIDC discovery returns new scopes
4. ⏳ Test OAuth flow with new scope model
5. ⏳ Deploy to production

​

Rollback Plan