Arazzo Extensions
<rapi-flow> supports three vendor extensions of Arazzo, as Redocly Respect defines them. They work in runs, in the diagram and in the MCP export. A fourth, x-mock-server-status-code, is RapiDoc’s own and only fills the run panel’s mock table.
| Extension | On | What it does |
|---|---|---|
x-security |
workflow, step | The credentials a request sends. |
x-operation |
step | Calls a URL outside the API sources. |
x-allowReserved |
step parameter | Sends reserved characters in a query value unencoded. |
x-mock-server-status-code |
step | The status codes the mock answers this step with in a run, prefilled in Mock Response Status. |
Credentials in the workflow (x-security)
Section titled “Credentials in the workflow (x-security)”<rapi-flow> supports the x-security extension of Redocly Respect, so an Arazzo file can say which credentials each request sends instead of relying on what the reader typed into the Authentication section. Put it on a step, or on the workflow for every step:
workflows: - workflowId: adoptPet inputs: type: object properties: apiKey: { type: string, format: password } token: { type: string, format: password } x-security: # every step - scheme: { type: http, scheme: bearer } values: { token: $inputs.token } steps: - stepId: checkPet operationId: getPetById x-security: # this step only - schemeName: api_key # a scheme of the step's OpenAPI source values: { apiKey: $inputs.apiKey }- Each entry has either
schemeName(a scheme in the step’s source’scomponents.securitySchemes) or an inlinescheme, plusvalues:apiKeyfor an API key (in: header,queryorcookie),usernameandpasswordfor HTTP Basic,tokenfor HTTP Bearer, OAuth 2 and OpenID Connect. - Values are usually
$inputs.<name>, or$steps.<id>.outputs.<name>for a token an earlier step returned. An input that is not given sends nothing for that entry. - The workflow’s entries are sent first, then the step’s, after the credentials entered in the page. Where two set the same header, query parameter or cookie, the later one wins, so the step’s override the workflow’s.
- Inputs with
format: passwordget a password field in the run panel, and the log shows them as••••••. The diagram lists each step’s credentials under Security with the scheme, and never shows a value written into the file itself. - HTTP Digest is not supported: a browser cannot read the API’s challenge across origins. A workflow that uses it is drawn, with a note that it cannot run.
In an MCP export, password inputs are arguments of the workflow’s tool, so the agent supplies them. To keep a secret away from the agent, leave it out of x-security and set the scheme’s environment variable instead.
Calls outside the API sources (x-operation)
Section titled “Calls outside the API sources (x-operation)”A step can call an endpoint that no source description describes, such as a file download link an earlier step returned, or a third-party API, with the x-operation extension of Redocly Respect. It takes the place of operationId:
steps: - stepId: upload operationId: uploadFile outputs: fileUrl: $response.body#/url - stepId: download x-operation: url: $steps.upload.outputs.fileUrl # or an absolute URL: https://cdn.example.com/files/{id} method: get successCriteria: - condition: $statusCode == 200urlis an absolutehttporhttpsURL, or a runtime expression;{$inputs.x}can be interpolated into a URL too.methodis any HTTP method, in any case.parameterswork as for other steps: query, header and cookie values are added, and a path parameter fills its{name}in the URL.requestBody,successCriteria, actions andoutputsare the same.- No source credentials are sent, since the URL belongs to no source. To send some, add
x-securitywith an inlinescheme(schemeNamehas no source to look in). - The diagram draws the step with a dashed border, its method and URL, and an external tag. A URL computed from an earlier step lists that step under URL, like any value passed between steps. The step does not open anything in the reference.
- Runs call the URL from the reader’s browser, so that server must allow cross-origin requests from the docs site; the log says so when the request fails. A mock does not answer these steps.
In an MCP export, the server makes the request. A URL written into the Arazzo file is always called; a URL computed at run time (from an input or a response) is called only on a host the workflow names (its API sources’ servers, or another step’s written-out URL), so an agent or an API can’t send the server to an address of its choosing. List more hosts in EXTERNAL_HOSTS (comma-separated, * for any), which the exported server, rapidoc mcp serve and rapidoc serve all read, or with the runtime’s externalHosts option.
Reserved characters in query values (x-allowReserved)
Section titled “Reserved characters in query values (x-allowReserved)”Query values are percent-encoded, so https://a.example/x is sent as https%3A%2F%2Fa.example%2Fx. When the API expects the value as is (a URL, a filter expression), set x-allowReserved: true on the step’s parameter, the Arazzo counterpart of OpenAPI’s allowReserved, as in Redocly Respect:
parameters: - name: filter in: query value: https://example.com/path/to;x,y x-allowReserved: true # ?filter=https://example.com/path/to;x,yThe reserved characters : / ? [ ] @ ! $ & ' ( ) * + , ; = are then sent unencoded; spaces and other characters are still encoded, and so is #, which would end the URL’s query. A query parameter with allowReserved: true in the OpenAPI document is sent the same way without the extension; x-allowReserved: false turns that off for one step.
Mock status codes (x-mock-server-status-code)
Section titled “Mock status codes (x-mock-server-status-code)”A workflow that shows a failure path, a retry or a goto, can carry the scenario it needs. Put the codes on the step, in the syntax of the mock-server-status-code attribute:
steps: - stepId: checkPet operationId: getPetById x-mock-server-status-code: "cycle:503,503,200" # fails twice, then succeeds - stepId: placeOrder operationId: placeOrder x-mock-server-status-code: "random:200,500"The value fills the step’s row of the run panel’s Mock Response Status table, where the reader can change it before a run: codes without a prefix are used in turn, one per attempt; random: picks one at random. A number (404) or a list ([503, 200]) works too. It only applies when the run is mocked (a paired element with mock-server, or server-is-mock); a real server, and the MCP export, ignore it. Arazzo allows x- extensions on steps, so the file stays valid for other tools.