OAuth 2.1 Authentication

Agent skill: nitrostack-python-auth-security

Wire OAuthModule.for_root(...) from environment, then guard tools:

from nitrostack import tool, use_guards, OAuthGuard, ExecutionContext
from guards.oauth_guard import create_scope_guard  # generated in python-oauth template

@tool(name="search_flights", description="...", input_schema=SearchFlightsInput)
@use_guards(OAuthGuard, create_scope_guard(["read"]))
async def search_flights(self, input: SearchFlightsInput, context: ExecutionContext) -> dict:
    subject = context.auth.subject if context.auth else None
    ...

Token introspection fills context.auth. aud is a list.

OAUTH_REQUIRED: when unset / not required, OAuthGuard allows requests with no token (Studio mock flights). Do not fail closed unless you set the env for production.

The python-oauth template includes OAUTH_SETUP.md with JWKS vs introspection, scopes, and PKCE.

Helpers: has_scope, has_any_scope, has_all_scopes, require_scopes, generate_www_authenticate_header, PKCE (generate_code_verifier, generate_code_challenge, verify_pkce), CIMD (resolve_cimd, validate_client_identifier_url).

Next steps

• OAuth 2.1 Guide
• OAuth Template