# Arazzo Extensions

> The Arazzo vendor extensions <rapi-flow> supports - x-security, x-operation and x-allowReserved as Redocly Respect defines them, and its own x-mock-server-status-code.

`<rapi-flow>` supports three vendor extensions of Arazzo, as [Redocly Respect](https://redocly.com/docs/respect/extensions/) defines them. They work in runs, in the diagram and in the [MCP export](https://rapidocui.com/docs/ai/mcp-server/#workflows-as-tools). 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`](/docs/extensions/#credentials-in-the-workflow-x-security) | workflow, step | The credentials a request sends. |
| [`x-operation`](/docs/extensions/#calls-outside-the-api-sources-x-operation) | step | Calls a URL outside the API sources. |
| [`x-allowReserved`](#reserved-characters-in-query-values-x-allowreserved) | step parameter | Sends reserved characters in a query value unencoded. |
| [`x-mock-server-status-code`](#mock-status-codes-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`)

`<rapi-flow>` supports the `x-security` extension of [Redocly Respect](https://redocly.com/docs/respect/extensions/x-security), 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:

```yaml
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's `components.securitySchemes`) or an inline `scheme`, plus `values`: `apiKey` for an API key (`in: header`, `query` or `cookie`), `username` and `password` for HTTP Basic, `token` for 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: password` get 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](https://rapidocui.com/docs/ai/mcp-server/#workflows-as-tools), 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`)

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](https://redocly.com/docs/respect/extensions/x-operation). It takes the place of `operationId`:

```yaml
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 == 200
```

- `url` is an absolute `http` or `https` URL, or a runtime expression; `{$inputs.x}` can be interpolated into a URL too. `method` is any HTTP method, in any case.
- `parameters` work as for other steps: query, header and cookie values are added, and a path parameter fills its `{name}` in the URL. `requestBody`, `successCriteria`, actions and `outputs` are the same.
- No source credentials are sent, since the URL belongs to no source. To send some, add [`x-security`](/docs/extensions/#credentials-in-the-workflow-x-security) with an inline `scheme` (`schemeName` has 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](https://rapidocui.com/docs/ai/mcp-server/#workflows-as-tools), 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`)

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](https://redocly.com/docs/respect/extensions/x-allow-reserved):

```yaml
parameters:
  - name: filter
    in: query
    value: https://example.com/path/to;x,y
    x-allowReserved: true        # ?filter=https://example.com/path/to;x,y
```

The 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`)

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`](https://rapidocui.com/docs/mocking/in-browser/#simulating-errors) attribute:

```yaml
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](/docs/running/#the-in-browser-mock) 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.
