{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"x-security-extension","__idx":0},"children":["x-security extension"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-security"]}," extension to define authorization flows based on OpenAPI security schemes."," ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/respect"},"children":["Respect"]}," automatically constructs appropriate authorization headers, queries, or cookies based on your parameters."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration-options","__idx":1},"children":["Configuration options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"20%","data-label":"Field name"},"children":["Field name "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Type"},"children":["Type "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["schemeName"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Name of the security scheme from your OpenAPI specification."," ","Use with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationPath"]}," at the step level."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["values"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Key-value pairs for security scheme parameters (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}," for Basic Authentication)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OR"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"20%","data-label":"Field name"},"children":["Field name "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Type"},"children":["Type "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["scheme"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/security-schemes"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["securitySchemes"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Inline security scheme definition."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["values"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Key-value pairs for security scheme parameters."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-authentication-types","__idx":2},"children":["Supported authentication types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Authentication type"},"children":["Authentication type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Security scheme"},"children":["Security scheme"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required values"},"children":["Required values"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Basic Authentication"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type: http",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"scheme: basic"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Digest Authentication"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type: http",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"scheme: digest"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bearer Authentication"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type: http",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"scheme: bearer",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"bearerFormat?: JWT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API Keys"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["type: apiKey",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"in: header | query | cookie",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"name: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiKey"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-security-schemes","__idx":3},"children":["Configure security schemes"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Reference existing scheme","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reference a security scheme from your OpenAPI document's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components.securitySchemes"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: fetchProducts\n    steps:\n      - stepId: getItemsStep\n        operationId: getItems\n        x-security:\n          - schemeName: ApiKeyAuth\n            values:\n              apiKey: $inputs.API_KEY\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example uses an API key from your workflow inputs to authenticate requests."]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Define inline scheme","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define a security scheme directly in your workflow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: fetchProducts\n    steps:\n      - stepId: getItemsStep\n        x-security:\n          - scheme:\n              type: http\n              scheme: basic\n            values:\n              username: admin\n              password: $inputs.PASSWORD\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example sets up Basic Authentication using credentials from your workflow inputs."]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Combine multiple schemes","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apply multiple security schemes to a single request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: fetchProducts\n    steps:\n      - stepId: getItemsStep\n        operationId: getItems\n        x-security:\n          - schemeName: ApiKeyAuth\n            values:\n              apiKey: $inputs.API_KEY\n          - scheme:\n              type: http\n              scheme: basic\n            values:\n              username: admin\n              password: $inputs.PASSWORD\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example combines API Key authentication with Basic Authentication."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"apply-security-at-different-levels","__idx":4},"children":["Apply security at different levels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apply security configuration at either the step or workflow level:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-level-security","__idx":5},"children":["Step-level security"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: fetchProducts\n    steps:\n      - stepId: getItemsStep\n        x-security:\n          # Security configuration\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"workflow-level-security","__idx":6},"children":["Workflow-level security"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: fetchProducts\n    x-security:\n      # Security configuration\n    steps:\n      - stepId: getItemsStep\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Step-level security takes precedence over workflow-level security when conflicts occur."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choose-between-schemename-and-scheme","__idx":7},"children":["Choose between schemeName and scheme"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schemeName"]},": Reference an existing OpenAPI security scheme."," ","Use at the step level with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationPath"]},"."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schemeName"]}," cannot be used with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-operation"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheme"]},": Define a security scheme inline."," ","Use at any level without OpenAPI specification binding."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"compare-parameters-and-x-security","__idx":8},"children":["Compare parameters and x-security"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-security"]}," instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameters"]}," for authentication to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automatically handle security scheme transformations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Place values in the correct location."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Simplify configuration."]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Using parameters","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"parameters:\n  - name: Authorization\n    in: header\n    value: 'Bearer {$inputs.TOKEN}'\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Using x-security with schemeName","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"x-security:\n  - schemeName: BearerAuth\n    values:\n      token: $inputs.TOKEN\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Using x-security with scheme","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"x-security:\n  - scheme:\n      type: http\n      scheme: bearer\n    values:\n      token: $inputs.TOKEN\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-multiple-security-schemes","__idx":9},"children":["Handle multiple security schemes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Process multiple security schemes in top-to-bottom order."," ","Merge schemes without conflicts."," ","For conflicting headers (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]},"), the last processed scheme takes precedence."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"secure-secret-management","__idx":10},"children":["Secure secret management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store secrets in workflow inputs and reference them using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$inputs.<NAME>"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define an input parameter and use it inside values:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: fetchProducts\n    # Define an input parameter used by this workflow.\n    inputs:\n      type: object\n      properties:\n        TOKEN:\n          type: string\n          format: password\n    steps:\n      stepId: getItemsStep\n      x-security:\n        - scheme:\n            type: http\n            scheme: bearer\n          values:\n            # Use the input parameter.\n            token: $inputs.TOKEN\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass the secret when running the workflow:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx @redocly/cli respect arazzo-workflow.yaml --input TOKEN=<your-secret-value>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-scheme-examples","__idx":11},"children":["Authentication scheme examples"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Basic Auth","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"x-security:\n  - scheme:\n      type: http\n      scheme: basic\n    values:\n      username: user@example.com\n      password: $inputs.PASSWORD\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generates: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Basic dXNlckBleGFtcGxlLmNvbTpzZWNyZXQ="]}]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Digest Auth","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"x-security:\n  - scheme:\n      type: http\n      scheme: digest\n    values:\n      username: user@example.com\n      password: $inputs.PASSWORD\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handles the Digest Authentication flow automatically:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receives ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WWW-Authenticate"]}," header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Computes required hashes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sends authenticated request."]}]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Bearer Auth","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"x-security:\n  - scheme:\n      type: http\n      scheme: bearer\n    values:\n      token: $inputs.TOKEN\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generates: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <your-secret-value>"]}]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API Key","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"x-security:\n  - scheme:\n      type: apiKey\n      in: query\n      name: key\n    values:\n      apiKey: $inputs.API_KEY\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generates: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?key=<your-secret-value>"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":12},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/arazzo/what-is-arazzo"},"children":["Arazzo overview"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/respect/commands"},"children":["Respect commands"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference/security-schemes"},"children":["Security schemes"]}]}]}]},"frontmatter":{},"tagList":["html","tab","table","tabs"],"title":"x-security extension","lastModified":"2025-07-25T14:12:03.000Z"}