Advanced10 min

Agent Server Authentication & Authorization

Full auth system for Agent Server: @auth.authenticate for identity verification, @auth.on for resource-specific access control, and agent authentication for delegated MCP access.

Quick Reference

→@auth.authenticate handler verifies identity from headers, tokens, or OAuth — runs on every request
→@auth.on authorization handlers control access per resource type (threads, assistants, crons)
→Filter operations ($eq, $contains) restrict which resources a user can see/modify
→Common patterns: single-owner, permission-based, multi-tenant organization scoping
→Agent authentication: agents can act on behalf of users with scoped tokens for MCP servers
→OpenAPI security documentation auto-generated from auth configuration

Authentication: Who Are You?

@auth.authenticate — verify identity on every request

The auth object

The dict returned by @auth.authenticate becomes available to all @auth.on handlers and can be used for authorization decisions. Include any user metadata you need: user ID, org ID, roles, permissions, plan tier.

Authorization: What Can You Do?

@auth.on — resource-specific access control

Common Authorization Patterns

Pattern	Implementation	Use Case
Single-owner	Filter threads by owner = user_id	Personal assistant, each user sees only their threads
Permission-based	Check ctx.user['permissions'] list	Role-based access (admin, editor, viewer)
Multi-tenant	Filter by org_id from JWT	B2B SaaS — users see only their organization's data
Shared + private	Filter by owner OR shared=true	Team workspaces with personal and shared threads

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.