Identity federation: add user and service account examples, correct stale claims (DOCS-2516)

[mdlinville]

Resolves DOCS-2516 (migrated from WBDOCS-1473, split from WB-19908 "Identity Federation Enhancements").

The ticket asked for a user-account example, a service-account example, notes on known usability issues, and removal of the "Preview" label. Everything except the Preview label is here — see the open question at the bottom.

Corrections to existing content

While sourcing the examples against wandb/core@master, four statements on the page turned out to be wrong or stale:

Page said	Source	Reality
The sub claim must equal the user's email address	services/gorilla/internal/oidc/storage.go (CreateAccessTokenSession)	Email is resolved as sub → email claim → any claim whose name contains email. Shipped for WB-27624 in server v0.74.0.
Settings → Set up JWT Issuer (one issuer)	frontends/app/src/pages/OrgDashboard/AuthenticationSettings/AuthenticationSettings.tsx	UI is a JWT Issuers list with Add JWT Issuer. Multiple issuers per org are supported.
Service account: pick Federated Identity, provide Subject	frontends/app/src/pages/Billing/AccountSettings/ServiceAccountsTab/CreateServiceAccountDrawerForm.tsx	The drawer also requires selecting a JWT Issuer, the option is disabled until an issuer exists, and the flow is reachable from org account settings as well as the team tab.
Set FEDERATED_AUTH_AUDIENCES=wandb to skip audience validation	services/gorilla/cmd/gorilla_api.go:326, cmd/config.go:65	That only sets the expected audience to its default. SKIP_AUDIENCE_VALIDATION is the actual skip flag.

New content

• Examples — a user-account example and an external-service-account example, each with a decoded JWT payload and the matching workload config (shell + wandb.init(); Kubernetes projected service account token).
• JWT validation reworked into a claim-by-claim table, adding three requirements that weren't documented: iat is required, exp − iat must be ≤ 24 hours (fosite default, not overridden in gorilla), and jti is optional but replay-checked.
• Audience requirements split by deployment. Multi-tenant Cloud requires exactly one aud value, the org name, and it isn't configurable — WB-39012 (Mistral) is still open for that.
• Troubleshooting — four failures seen in support this month:
  • jti_known replay when login() and init() resolve WANDB_CREDENTIALS_FILE differently (EA, 2026-08-26).
  • "No public JWK was registered for issuer … and subject …" usually meaning a bad aud, not a bad sub (Mistral, WB-39012).
  • Deleted federated service accounts permanently claiming issuer+subject (WB-39165, open).
  • Public API support landing later than wandb.init() support.
• Scope note that Weave and Serverless Inference don't support identity federation yet (WB-37733).

Also updated

platform/hosting/env-vars.mdx and platform/hosting/iam/advanced_env_vars.mdx: WANDB_IDENTITY_TOKEN_FILE was described as "the absolute path to the local directory where Java Web Tokens (JWTs) are stored" — it's a file path, and they're JSON Web Tokens. Added WANDB_CREDENTIALS_FILE, FEDERATED_AUTH_AUDIENCES, and SKIP_AUDIENCE_VALIDATION, none of which were in the env var reference.

Open question for review

The "Preview" label is still on the page. The ticket asked to remove it, but I couldn't find a GA decision anywhere, and there's some evidence against: Weave and Inference support is still in flight, MT Cloud aud configurability is an open FR, and there's an open service-account deletion bug. @RyanBuccellato — is identity federation GA? If so I'll drop the note in a follow-up commit.

Two smaller things worth a second pair of eyes:

• I state that the JWT Issuer and Subject are fixed at creation time. I inferred that from oauth.ts exposing only createClient/revokeClient with no update mutation.
• I state that a federated service account can still be issued an API key afterward via the row menu, since ServiceAccountsTabContent.tsx:493 gates Create API key only on isApiKeyCreationDisabled and apiKeyCount.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	Aug 31, 2026, 9:51 PM

---

Page	Change
Env Vars	Changed · +2 −1
Advanced Env Vars	Changed · +4 −1
Identity Federation	Changed · +222 −34

_{Updated 2026-09-01 21:54:40 UTC for deployment · 61c5467.}

[github-actions]

Readability impact

Word-weighted Flesch-Kincaid grade change across 3 changed pages: -0.5 (easier).

Lower Flesch-Kincaid grade and higher reading ease both mean easier to read. This check is informational and never blocks a PR.

Human readability

Page	FK grade before	FK grade after	FK Δ	Reading ease Δ	Direction
platform/hosting/env-vars.mdx	12.6	12.6	+0.0	+0.0	unchanged
platform/hosting/iam/advanced_env_vars.mdx	14.3	14.3	+0.0	+0.0	unchanged
platform/hosting/iam/identity_federation.mdx	10.6	10.0	-0.6	+2.2	easier

AI agent comprehension

Rated 0-3 (higher is easier for an agent to parse and act on).

Page	Before	After	Δ
platform/hosting/iam/identity_federation.mdx	3	3	+0
platform/hosting/env-vars.mdx	3	3	+0
platform/hosting/iam/advanced_env_vars.mdx	3	3	+0

_{Curated-docs baseline median FK grade by type: conceptual 10.5, procedural 8.8, reference 9.4.}

From workflow run 33563275050

[w-b-hivemind]

HiveMind Sessions

2 sessions · 1h 11m · $22

Session	Agent	Duration	Tokens	Cost	Lines
Set Up Locadex Auto-Translation for CoreWeave Docs a961c8ed-724a-45a9-a642-46218238c498	claude	36m	78.1K	$10	+49 -0
Investigating DOCS-2516 via Glean and Core 06a05099-59e2-4799-88fa-86886d8731a3	claude	35m	65.3K	$12	+0 -0
Total		1h 11m	143.4K	$22	+49 -0

View all sessions in HiveMind →

Run claude --resume a961c8ed-724a-45a9-a642-46218238c498 to pickup where you left off.

[github-actions]

🔗 Link Checker Results

✅ All links are valid!

No broken links were detected.

Preview: https://wb-21fd5541-docs-2516.mintlify.site