docs: add secret references for static token authentication

[markphelps]

Add documentation explaining how to use secret references to securely manage static authentication tokens in Flipt v2.

Changes

• Updated static token auth docs with file and Vault secret reference examples
• Added cross-references between authentication, secrets, and secret references docs
• Extended secrets.mdx usage examples to include static token authentication

Closes #349

Generated with Claude Code

[claude]

Review

Overall this is a well-structured addition that fills a clear gap in the docs. The cross-referencing between authentication, secrets, and the overview page is solid. A few notes below:

Inconsistent quoting style

The credential values in authentication.mdx use double-quoted strings ("${secret:file:ci-token}"), but the equivalent examples added to secrets.mdx leave them unquoted (${secret:file:ci-token}).

Both are valid YAML, but it's inconsistent within the same PR. The existing pattern in authentication.mdx (e.g., credential: "some_token_credential") uses quotes, so the new examples there are fine. The secrets.mdx file follows its own existing unquoted style (e.g., key: ${secret:file:csrf-key}), so those are also fine in isolation—but a reader who compares both pages may wonder whether quoting matters. Worth at least acknowledging in a comment, or keeping consistent across both files.

Missing inline comments in authentication.mdx

The secrets.mdx file provider example helpfully annotates what each reference resolves to:

credential: ${secret:file:ci-token} # References /etc/flipt/secrets/ci-token

The new examples in authentication.mdx omit these. Adding them would make the examples more self-contained for readers who land on the authentication page without reading the secrets page first.

Two tokens in file example, one in Vault example

The file provider block shows two tokens (ci_token and dev_token), but the Vault block shows only one. Having two in the file example nicely illustrates that multiple tokens are supported, but the asymmetry feels a little uneven. Either trimming the file example to one token for simplicity or adding a second token to the Vault example would tighten things up.

Nit: secrets.mdx Vault example omits required: true

The authentication.mdx examples include required: true, but the Vault provider block added to secrets.mdx omits it. The file provider example there also omits it, so this is internally consistent within secrets.mdx—just flagging it in case fully runnable snippets are the goal for that page.

---

None of these are blockers—the docs are accurate, links resolve to the correct anchors, and the new content follows the established page structure. Good work closing #349.

[claude]

Review (Corrected)

A previous automated review was left on this PR with several inaccurate observations. This comment supersedes it with accurate findings.

What is good

• The new 'Using Secret References' section in authentication.mdx is well-structured. Both the file provider and Vault examples use consistent quoted strings, include helpful inline comments, show two tokens to illustrate multi-token support, and include required: true for completeness.
• The secrets.mdx changes correctly update existing unquoted secret references to quoted strings for consistency, and required: true is properly added to both the file and Vault provider blocks.
• Cross-links between authentication, secrets, and the overview page are correct and use proper relative paths.
• The Tip callout pointing to the secrets page is a nice touch.

One minor issue

In secrets.mdx, the Vault provider token example is missing the inline comment that the file provider example has.

The file provider includes a comment: credential followed by the secret reference followed by '# References /etc/flipt/secrets/ci-token'

The Vault provider omits a similar annotation: credential followed by the vault secret reference with no comment.

Adding a comment like '# References flipt/tokens secret, key: ci-token' would make it consistent with the file provider example and with the Vault examples in authentication.mdx.

---

This is a solid addition overall—accurate, well-linked, and consistent with existing patterns. The minor comment omission is the only thing worth addressing before merging.