docs: specify the AGENTEX_AUTH_URL auth provider HTTP contract

[smoreinis]

What

Documents the HTTP contract that a service pointed to by AGENTEX_AUTH_URL must implement, so the auth provider becomes a clearly documented extension point. A self-hosted / open-source deployment can implement this contract directly without depending on any Scale-internal auth service.

New doc: agentex/docs/docs/development_guides/auth_provider_contract.md (added to the docs nav under Development Guides).

Contract covered

• POST /v1/authn — authenticate from forwarded request headers, return an opaque principal context.
• POST /v1/authz/* — check, search, grant, revoke, register, deregister, with request/response shapes and status-code semantics.

The contract was derived from the existing integration on both sides: the consumer-side proxies/middleware in agentex/src (which define what gets sent and how status codes are interpreted) and the reference provider's routers/schemas.

Key points the doc makes explicit

• The principal is an opaque round-trip object. Agentex never inspects it — it caches the /v1/authn result and passes it back verbatim on every authz call. This is what lets a provider own its own identity shape (and makes OIDC/Entra ID pluggable with no Agentex change).
• Status code is the API. 200=success, 401=unauthenticated, 403=denied, 5xx=service errors. check returns no meaningful body.
• register/deregister must exist. Agentex calls them on every resource create/delete when a provider is configured, so omitting them turns creates into 500s. Their behavior can be a trivial 200 no-op.

Implementation guidance

The doc includes two concrete sketches:

1. Authenticating against an OIDC provider (e.g. Entra ID) — validate the bearer JWT against the tenant JWKS, map standard claims into a principal.
2. An "allow everything" single-account authorization model — check/grant/revoke/register/deregister collapse to 200, but search cannot be a no-op because its items list is consumed as an inclusion filter (WHERE id IN (...)); returning [] hides everything.

Note for reviewers — one follow-up

The recommended "allow everything" approach for search is a wildcard sentinel (e.g. {"items": null}) that the Agentex authorization proxy maps to its existing "no filter" code path. That sentinel is not yet part of the shipped contract — supporting a truly stateless permissive provider would need a small proxy change. The doc calls this out explicitly as a recommended addition rather than describing it as current behavior.

Type of change

Documentation only. No code or runtime behavior changes.

Greptile Summary

This PR adds a new reference doc (agentex/docs/docs/development_guides/auth_provider_contract.md) that specifies the HTTP contract a service pointed to by AGENTEX_AUTH_URL must implement, making the auth provider a documented extension point for self-hosted deployments. The contract was cross-checked against the actual consumer-side code in adapter_agentex_authn_proxy.py, adapter_agentex_authz_proxy.py, and middleware_utils.py and is accurate in all request/response shapes, status-code semantics, allowlist routes, header-stripping, and the caching behavior.

• New doc (auth_provider_contract.md): covers POST /v1/authn and all six POST /v1/authz/* endpoints with wire-format examples, status-code semantics, and important behavioral callouts (principal opacity, authn 5xx collapse, search as an inclusion filter, register/deregister being mandatory).
• mkdocs.yml: single nav entry added under Development Guides, placed between Webhooks and Enterprise Edition.

Confidence Score: 4/5

Safe to merge after resolving the broken forward reference; all documented behavior has been verified against the actual implementation code.

The doc is accurate and well-researched, but line 273 explicitly directs readers to implementation guidance that is not present in the file — a provider author implementing the permissive use case (the most likely open-source scenario) will follow that reference and find nothing.

agentex/docs/docs/development_guides/auth_provider_contract.md — the dangling "(see below)" at line 273 needs either the missing implementation sketches added or the forward reference removed.

Important Files Changed

Filename	Overview
agentex/docs/docs/development_guides/auth_provider_contract.md	New reference doc for the AGENTEX_AUTH_URL provider contract; content is accurate and well-structured, but a forward "(see below)" reference at line 273 points to implementation sketches that are absent from the file.
agentex/docs/mkdocs.yml	Adds the new auth provider contract page to the Development Guides nav section between Webhooks and Enterprise Edition; no issues.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Middleware as Agentex Middleware
    participant Provider as Auth Provider
    participant Handler as Agentex Handler

    Client->>Middleware: HTTP Request (with headers)
    Note over Middleware: Allowlisted route or x-agent-api-key? Skip provider
    Middleware->>Provider: POST /v1/authn (forwarded headers, empty body)
    alt 200 OK
        Provider-->>Middleware: principal context JSON
        Middleware->>Middleware: Cache principal keyed on headers
        Middleware->>Handler: Request + principal_context
        Handler->>Provider: POST /v1/authz/check or search or register etc
        alt 200
            Provider-->>Handler: success body
            Handler-->>Client: Response
        else 403
            Provider-->>Handler: denied
            Handler-->>Client: 403 Forbidden
        else 5xx or network error
            Provider-->>Handler: error
            Handler-->>Client: 5xx propagated
        end
    else any non-200 including 5xx
        Provider-->>Middleware: error
        Middleware-->>Client: 401 Unauthorized
    end

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
agentex/docs/docs/development_guides/auth_provider_contract.md:273
**Dangling "(see below)" forward reference**

The callout at this line directs implementers to "see below" for how a permissive provider should handle `register`/`deregister`, but the doc ends three lines later with the endpoint summary table — there is no "below" section. The PR description mentions two concrete implementation sketches (OIDC / Entra ID and an "allow everything" model), but they were not included in the file. A provider author following this reference will find nothing, leaving the most common open-source use case undocumented.

### Issue 2 of 2
agentex/docs/docs/development_guides/auth_provider_contract.md:189
**`check` 200 body must be valid JSON**

The note "(body is not otherwise read)" may lead a provider author to return an empty or plain-text `200`, but `HttpRequestHandler.post_with_error_handling` always calls `response.json()` on every `200` response and raises `ServiceError` if parsing fails. An empty body or a non-JSON string like `"OK"` would cause a `ServiceError` on every `check` call. The doc already shows `{ "success": true }` as the suggested shape, but clarifying that **valid JSON is required** (even though the content is ignored) would prevent this trap.

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into docs/auth-provi..." | Re-trigger Greptile}

[scalelaszlo]

nitpick, but can you add linebreaks between them?