Skip to content
Last updated

x-security extension

Use the x-security extension to define authorization flows based on OpenAPI security schemes. Respect automatically constructs appropriate authorization headers, queries, or cookies based on your parameters.

Configuration options

Field name Type Description
schemeNamestringREQUIRED. Name of the security scheme from your OpenAPI specification. Use with operationId or operationPath at the step level.
valuesobjectREQUIRED. Key-value pairs for security scheme parameters (e.g., username, password for Basic Authentication).

OR

Field name Type Description
schemesecuritySchemesREQUIRED. Inline security scheme definition.
valuesobjectREQUIRED. Key-value pairs for security scheme parameters.

Supported authentication types

Authentication typeSecurity schemeRequired values
Basic Authenticationtype: http
scheme: basic		username, password
Digest Authenticationtype: http
scheme: digest		username, password
Bearer Authenticationtype: http
scheme: bearer
bearerFormat?: JWT		token
API Keystype: apiKey
in: header | query | cookie
name: string		apiKey

Configure security schemes

Reference a security scheme from your OpenAPI document's components.securitySchemes:

workflows:
  - workflowId: fetchProducts
    steps:
      - stepId: getItemsStep
        operationId: getItems
        x-security:
          - schemeName: ApiKeyAuth
            values:
              apiKey: $inputs.API_KEY

This example uses an API key from your workflow inputs to authenticate requests.

Apply security at different levels

Apply security configuration at either the step or workflow level:

Step-level security

workflows:
  - workflowId: fetchProducts
    steps:
      - stepId: getItemsStep
        x-security:
          # Security configuration

Workflow-level security

workflows:
  - workflowId: fetchProducts
    x-security:
      # Security configuration
    steps:
      - stepId: getItemsStep

Note: Step-level security takes precedence over workflow-level security when conflicts occur.

Choose between schemeName and scheme

  • schemeName: Reference an existing OpenAPI security scheme. Use at the step level with operationId or operationPath. schemeName cannot be used with x-operation.
  • scheme: Define a security scheme inline. Use at any level without OpenAPI specification binding.

Compare parameters and x-security

Use x-security instead of parameters for authentication to:

  • Automatically handle security scheme transformations.
  • Place values in the correct location.
  • Simplify configuration.
parameters:
  - name: Authorization
    in: header
    value: 'Bearer {$inputs.TOKEN}'

Handle multiple security schemes

Process multiple security schemes in top-to-bottom order. Merge schemes without conflicts. For conflicting headers (e.g., Authorization), the last processed scheme takes precedence.

Secure secret management

Store secrets in workflow inputs and reference them using $inputs.<NAME>:

  1. Define an input parameter and use it inside values:
workflows:
  - workflowId: fetchProducts
    # Define an input parameter used by this workflow.
    inputs:
      type: object
      properties:
        TOKEN:
          type: string
          format: password
    steps:
      stepId: getItemsStep
      x-security:
        - scheme:
            type: http
            scheme: bearer
          values:
            # Use the input parameter.
            token: $inputs.TOKEN
  1. Pass the secret when running the workflow:
npx @redocly/cli respect arazzo-workflow.yaml --input TOKEN=<your-secret-value>

Authentication scheme examples

x-security:
  - scheme:
      type: http
      scheme: basic
    values:
      username: user@example.com
      password: $inputs.PASSWORD

Generates: Authorization: Basic dXNlckBleGFtcGxlLmNvbTpzZWNyZXQ=

Resources

 
Next page