feat: add service account id to auth cache

[alvinkam2001]

Summary

Adds service_account_id to the principal-identity field list in _create_authorization_cache_key.

Without this, two SA principals in the same account on the same resource would hash to the same authz cache key — one SA's cached permission decision could be served to another SA's request. With per-principal grants supported in agentex_permissions, that's a real correctness risk for SA flows.

Also documents the new user_id vs service_account_id mutual exclusion in configuration.md.

Related PRs (ship together)

• This PR (auth cache key) — scaleapi/scale-agentex#210
• SGP backend — https://github.com/scaleapi/scaleapi/pull/141104
• agentex-auth — https://github.com/scaleapi/agentex/pull/333
• scale-agentex-python (SDK validator) — add service account id as option to register agentex agent scale-agentex-python#332

Test Plan

• The code change is a 1-line addition to a static field list; correctness is obvious by inspection. The repo doesn't currently have unit-level tests for AuthenticationCache — adding one for this single line would establish a new convention for what's effectively a 1-character change.
• ruff check + ruff format --check clean.
• Local pre-commit hooks pass (TruffleHog, ruff, ruff-format).

Greptile Summary

This PR fixes a correctness bug in _create_authorization_cache_key where two service-account principals sharing the same account_id, agent_id, and other fields would produce an identical cache key, causing one SA's cached authorization decision to be served to a different SA's request. The fix adds service_account_id to the field-extraction list, making per-SA grants correctly isolated. The accompanying configuration.md update clearly documents the user_id / service_account_id mutual-exclusion contract.

Confidence Score: 5/5

Safe to merge — the change is a minimal, clearly correct addition with no regressions.

The code change is a single field added to an existing field-extraction list; logic is straightforward and directly addresses the described correctness bug. No new control flow, no data-loss risk, no security issues. All remaining observations are P2 at most.

No files require special attention.

Important Files Changed

Filename	Overview
agentex/src/api/authentication_cache.py	Adds service_account_id to the principal field-extraction list in _create_authorization_cache_key; correctly fixes cache-key collision between distinct SA principals.
agentex/docs/docs/configuration.md	Documents the new service_account_id field and its mutual exclusion with user_id; adds a YAML example and updated best-practice bullets.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Authorization check request\nresource_type, resource_selector, operation, principal_context] --> B[_create_authorization_cache_key]
    B --> C{principal_context\npresent?}
    C -- No --> D[empty principal_key_data]
    C -- Yes --> E{has __dict__?}
    E -- Yes --> F[use __dict__]
    E -- No --> G{is dict?}
    G -- Yes --> H[use as-is]
    G -- No --> I[wrap as value string]
    F & H & I --> J[Extract fields:\nuser_id\nservice_account_id NEW\naccount_id\nagent_id\nid / sub / email]
    J --> K{any fields\nfound?}
    K -- Yes --> L[principal_key_data = extracted fields]
    K -- No --> M[principal_key_data = hash of full context]
    L & M & D --> N[cache_data dict\nresource_type + resource_selector\n+ operation + principal]
    N --> O[SHA-256 hash → authz: key]
    O --> P{cache hit?}
    P -- Yes --> Q[Return cached allow/deny]
    P -- No --> R[Run authorization check\nStore result in cache]

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into akam/agentex-SA..." | Re-trigger Greptile}

[declan-scale]

Just update the readme and should be good

[declan-scale]

Let's use this comment from before (in the open-source case don't use SGP): # Unique identifier for the user who is deploying the agent