Add schemeName support to x-security at the workflow level
@vadyvas is already working on this.
Since Oct 14, 2025.
- Dominant language
- TypeScript
- Stars
- 1.5k
- Forks
- 228
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 48
Description
Is your feature request related to a problem? Please describe.
Currently, in order to define security at the workflow level using x-security, we have to inline the entire security scheme. This leads to duplication when the scheme already exists and is referenced elsewhere in the API description. It makes workflows verbose and harder to maintain.
Describe the solution you'd like
Allow x-security at workflow level to support a schemeName field referencing an existing security scheme (via $sourceDescriptions) instead of requiring the full scheme object. Example:
sourceDescriptions:
- name: main
type: openapi
url: ../main/openapi.yaml
workflows:
- workflowId: workflowId
x-security:
- schemeName: $sourceDescriptions.main.UserCookie
values:
apiKey: {KEY}
Describe alternatives you've considered
The current workaround is to inline the scheme every time:
workflows:
- workflowId: workflowId
x-security:
- scheme:
type: apiKey
in: cookie
name: accessToken
values:
apiKey: {KEY}
This approach is repetitive and error-prone, especially when the same scheme is reused across multiple workflows.
Additional context
Referencing existing schemes improves maintainability and reduces duplication. A common use case is referencing a shared scheme like:
UserCookie:
$ref: ../common/security/UserCookie.yaml
Which is defined as:
type: apiKey
in: cookie
name: accessToken
description: Default authentication scheme for interaction between browser and API.
References
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.