@W-24145098 - docs: document WIF admin REST API endpoints (#1895)

* @W-24145098 - docs: document WIF admin REST API endpoints

Documents the new server.auth_federation endpoint added in PR #1894 on the
tableau/server-client-python main branch.

- New top-level section 'Auth Federation' in docs/api-ref.md, between
  'Authentication' and 'Connections'. Documents:
  - AuthFederationItem, AuthFederationConnectorItem, AuthFederationKeyItem
    class attribute tables.
  - 12 endpoint methods: get, enable, update, delete; create_connector,
    list_connectors, get_connector, delete_connector; create_key,
    activate_key, deactivate_key, delete_key.
  - Signature, parameters, return type, and example per method.
  - Server behavior notes callers can't derive from the signature:
    per-method 403/404 semantics, PAT/scope acceptance, orphan-key risk
    when create_key runs before enable, safe-rotation order for keys,
    and client-side UUID validation that raises ValueError on malformed
    ids before any HTTP call.
- _includes/docs_menu.html: adds an 'Auth Federation' entry in the API
  Reference sidebar between 'Authentication' and 'Connections'.

Requires REST API 3.30+ (Tableau Server release 26.3) and the WIF
feature enabled on the site; the server returns 403 otherwise, including
on get().

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Match updated key-rotation guidance from PR #1894

The code PR's docstring + CHANGELOG now clarify that the old key must be
retained in the site's JWKS until every JWT it signed has expired, and
only then deleted. The previous `create_key() -> activate_key(new) ->
delete_key(old)` sequence skipped that retain step; deleting the old key
immediately removes it from the JWKS and verifiers that fetch the key
set afterwards reject the still-valid tokens signed with it. Updated
the `auth_federation.delete_key` section here to match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Match delete_key docstring reframe from PR #1894

Code PR dropped the activate_key chain from `delete_key` and refocused
the docstring on the delete-vs-deactivate distinction (both stop new
signing with the key, but delete also pulls it from the JWKS, breaking
verification for still-unexpired tokens). Mirror that framing here.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sushmasreedharan-tableau

_includes/docs_menu.html

@@ -40,6 +40,9 @@
                 <li>
                     <a href="{{ site.baseurl }}/docs/api-ref#authentication">Authentication</a>
                 </li>
+                <li>
+                    <a href="{{ site.baseurl }}/docs/api-ref#auth-federation">Auth Federation</a>
+                </li>
                 <li>
                     <a href="{{ site.baseurl }}/docs/api-ref#connections">Connections</a>
                 </li>