Redocly
Add schemeName support to x-security at the workflow level
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.
