Move flowSecret to a request header for /flow/execute

[Malith-19]

Purpose

As part of the secured-by-default flow initiation model (parent: #2380), flowSecret was presented in the JSON request body of POST /flow/execute. In design discussion #2744, reviewers noted this is inconsistent with the server-level secret for the Direct API (atomic auth endpoints, #3762), which is sent via a request header. This PR moves flowSecret from the request body to a dedicated Flow-Secret header, aligning both mechanisms on the same transport convention.

Approach

• Removed the FlowSecret field from FlowRequest (backend/internal/flow/flowexec/model.go) and the flowSecret property from the InitialFlowRequest OpenAPI schema.
• Updated the flow execution handler to read the secret from the new Flow-Secret header (serverconst.FlowSecretHeaderName) instead of the decoded request body. The service-layer verification logic (checkDirectFlowInitiationAllowed) is unchanged since it already accepted the secret as a plain string parameter.
• Added FlowSecretHeaderName to backend/internal/system/constants/server_constants.go, alongside the other well-known request header constants.
• Updated api/flow-execution.yaml with a FlowSecret apiKey/header security scheme (mirroring the AtomicApiSecret scheme pattern) and removed flowSecret from the request body schema/examples.
• Updated integration test helpers (tests/integration/flow/common/utils.go, tests/integration/testutils/api_utils.go) and the Flow Secret guard suite (tests/integration/flow/authentication/flow_secret_flow_test.go) to send the secret via the header.
• Updated the two E2E admin-auth helpers that call /flow/execute directly to use the header.
• Updated the Flow Secret documentation section in docs/content/guides/guides/applications.mdx to describe the header instead of the body field.

Related Issues

• Fixes Move flowSecret from request body to a request header for /flow/execute #3795

Related PRs

• Gate atomic authentication APIs with a server-level secret #3762 — Gate atomic authentication APIs with a server-level secret (the X-Atomic-API-Secret header convention this change aligns with)
• Verify Flow Secret for backend applications at flow initiation #3476 — Verify Flow Secret for backend applications at flow initiation (introduced the Flow Secret verification this change moves to a header)
• Send flow secret via Flow-Secret header on native flow init javascript-sdks#20 — SDK support for sending the Flow Secret via the Flow-Secret header on native flow initiation

---

⚠️ Breaking Changes

🔧 Summary of Breaking Changes

POST /flow/execute no longer accepts flowSecret in the JSON request body.

💥 Impact

Any caller (SDKs, samples, custom integrations) that presented flowSecret in the request body must switch to sending it via the Flow-Secret request header, or flow initiation for Flow Secret-gated applications will fail with 401 Unauthorized.

🔄 Migration Guide

Move the flowSecret value out of the JSON body and set it as the Flow-Secret request header instead:

- POST /flow/execute
- Content-Type: application/json
-
- { "applicationId": "...", "flowType": "AUTHENTICATION", "flowSecret": "<secret>" }
+ POST /flow/execute
+ Content-Type: application/json
+ Flow-Secret: <secret>
+
+ { "applicationId": "...", "flowType": "AUTHENTICATION" }

---

Checklist

• Followed the contribution guidelines.
• Manual test round performed and verified. (Ran make lint, unit tests, and compiled/vetted the integration test module; did not spin up a live server for an end-to-end manual pass)
• Documentation provided.
• Tests provided. (Existing suites updated in place — no new test files)
  • Unit Tests
  • Integration Tests
• Breaking changes.
  • Breaking changes section filled.
  • breaking change label added.

Security checks

• Followed secure coding standards in WSO2 Secure Coding Guidelines
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

Summary by CodeRabbit

• New Features

  • Flow execution now accepts the Flow Secret through the Flow-Secret request header.
  • API documentation and examples were updated to reflect the new request format.

• Bug Fixes

  • Removed the Flow Secret from request bodies across flow initiation paths.
  • Updated flow execution handling so direct HTTP starts use the header-based secret consistently.

• Tests

  • Updated integration and end-to-end coverage to match the new header-based flow initiation behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2f6b8ef3-cfbc-4f30-b178-3fe25d1bcc45

📥 Commits

Reviewing files that changed from the base of the PR and between 923b7af and 6cb7988.

📒 Files selected for processing (10)

• api/flow-execution.yaml
• backend/internal/flow/flowexec/handler.go
• backend/internal/flow/flowexec/model.go
• backend/internal/system/constants/server_constants.go
• docs/content/guides/guides/applications.mdx
• tests/e2e/utils/authentication/admin-api-auth.ts
• tests/e2e/utils/server-setup/mfa-setup.ts
• tests/integration/flow/authentication/flow_secret_flow_test.go
• tests/integration/flow/common/utils.go
• tests/integration/testutils/api_utils.go

💤 Files with no reviewable changes (1)

• backend/internal/flow/flowexec/model.go

✅ Files skipped from review due to trivial changes (1)

• docs/content/guides/guides/applications.mdx

🚧 Files skipped from review as they are similar to previous changes (6)

• backend/internal/flow/flowexec/handler.go
• tests/e2e/utils/authentication/admin-api-auth.ts
• tests/e2e/utils/server-setup/mfa-setup.ts
• tests/integration/flow/common/utils.go
• tests/integration/flow/authentication/flow_secret_flow_test.go
• api/flow-execution.yaml

---

📝 Walkthrough

Walkthrough

The Flow Secret for POST /flow/execute moves from a JSON request body field (flowSecret) to a dedicated Flow-Secret HTTP header. Changes span the OpenAPI spec, backend handler/model, a new shared header-name constant, documentation, and e2e/integration test helpers.

Changes

Flow Secret header migration

Layer / File(s)	Summary
OpenAPI contract updates api/flow-execution.yaml	/flow/execute operation security and description now reference a FlowSecret header-based API-key scheme, the backend example drops flowSecret, and InitialFlowRequest no longer declares the flowSecret property.
Backend handler and model backend/internal/flow/flowexec/handler.go, backend/internal/flow/flowexec/model.go, backend/internal/system/constants/server_constants.go	A new FlowSecretHeaderName constant is defined, the handler now reads the secret from the Flow-Secret request header via serverconst, and FlowRequest no longer includes the flowSecret JSON field.
Guide update docs/content/guides/guides/applications.mdx	The applications guide instructs sending the Flow Secret via the Flow-Secret request header instead of the request body field.
E2E admin token retrieval tests/e2e/utils/authentication/admin-api-auth.ts, tests/e2e/utils/server-setup/mfa-setup.ts	Admin token helpers now send the admin native Flow Secret via the Flow-Secret header, removing it from the request body.
Integration helpers and auth tests tests/integration/testutils/api_utils.go, tests/integration/flow/common/utils.go, tests/integration/flow/authentication/flow_secret_flow_test.go	A shared FlowSecretHeaderName constant is added; initiateFlow/InitiateAuthFlowWithError set the header conditionally instead of adding flowSecret to the JSON body; executeNewFlow gains a flowSecret parameter, and guard tests are updated to exercise header-based secret presentation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant FlowExecHandler
  participant serverconst

  Client->>FlowExecHandler: POST /flow/execute with Flow-Secret header
  FlowExecHandler->>serverconst: read FlowSecretHeaderName
  FlowExecHandler->>FlowExecHandler: sanitize header value
  FlowExecHandler-->>Client: flow execution response

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately states the primary change: moving flowSecret to the /flow/execute request header.
Description check	✅ Passed	The description matches the template with Purpose, Approach, Related Issues, Breaking Changes, Checklist, and Security checks filled in.
Linked Issues check	✅ Passed	The core issue is implemented: flowSecret now comes from the Flow-Secret header, with matching handler, spec, docs, and test updates.
Out of Scope Changes check	✅ Passed	The changes stay focused on header-based flowSecret transport and related docs/tests, with no clear unrelated edits.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

docs/content/guides/guides/applications.mdx

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

tests/e2e/utils/authentication/admin-api-auth.ts

Parsing error: error TS5012: Cannot read file '/tsconfig.json': ENOENT: no such file or directory, open '/tsconfig.json'.

tests/e2e/utils/server-setup/mfa-setup.ts

Parsing error: error TS5012: Cannot read file '/tsconfig.json': ENOENT: no such file or directory, open '/tsconfig.json'.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ThaminduDilshan]

Don't this require a SDK change to send the flow secret in API requests? Better to merge this along with sdk bump