[synthetics] Document the request parameter

docs/en/observability/synthetics-create-test.asciidoc

@@ -76,7 +76,7 @@ The callback provides access to fresh Playwright `page`, `params`, `browser`, an
 
 [source,js]
 ----
-journey('Journey name', ({ page, browser, context, params }) => {
+journey('Journey name', ({ page, browser, context, params, request }) => {
   // Add steps here
 });
 ----
@@ -92,6 +92,9 @@ journey('Journey name', ({ page, browser, context, params }) => {
                 For example, if you want to use a different homepage depending on the `env`
                 (`localhost` for `dev` and a URL for `prod`). See <<synthetics-params-secrets>>
                 for more information.
+`request`::     A request object that can be used to make API requests independently of the browser
+                interactions. For example, to get authentication credentials or tokens in service of a
+                browser-based test. See <<synthetics-request-param>> for more information.
 
 
 [discrete]

docs/en/observability/synthetics-params-secrets.asciidoc

@@ -51,7 +51,7 @@ These options are discussed in detail in the sections below.
 [discrete]
 [[synthetics-dynamic-configs]]
 // lint ignore params
-== Using a config file to set params
+== Use a config file to set params
 
 Use a `synthetics.config.js` or `synthetics.config.ts` file to define variables your tests always need to be defined. 
 This file should be placed in the root of your synthetics project. 
@@ -77,16 +77,102 @@ Note that we use the `env` variable in the above example, which corresponds to t
 [discrete]
 [[synthetics-cli-params]]
 // lint ignore params
-== Using CLI arguments to set params
+== Use CLI arguments to set params
 
 To set parameters when running `elastic-synthetics` on the command line, use the `--params` or `-p` flag to the `elastic-synthetics` program. The provided map is merged over any existing variables defined in the `synthetics.config.{js,ts}` file.
 
 To override the `url` parameter, you would run: `elastic-synthetics . --params '{"url": "http://localhost:8080"}'`
 
+[discrete]
+[[synthetics-request-param]]
+== Use the `request` parameter
+
+Use the `request` parameter to make API requests independently of the browser interactions.
+
+// Link to Playwright docs?
+// https://playwright.dev/docs/test-api-testing#sending-api-requests-from-ui-tests
+
+NOTE: The `request` parameter is not intended to be used for writing pure API tests. Instead, it is a way to support
+writing plain HTTP requests in service of a browser-based test.
+
+Below is an example of how to use the `request` object to communicate with HTTP endpoints.
+The example demonstrates how to retrieve a token from an HTTP endpoint and use it in a subsequent webpage request.
+
+[source,js]
+-----
+import { journey, step, expect } from '@elastic/synthetics';
+
+journey('Retrieve and use HTTP Headers', ({ page, params, request }) => {
+  // We will populate these variable from example HTTP API responses
+  let apiKey;
+  let decodedApiKey;
+
+  // We will use httpbin.org endpoints for demonstration
+  const apiBaseUrl = 'https://httpbin.org';
+
+  // Let's say we expect the following header key:value from an Auth API
+  const exampleAPIHeaderKey = 'x-api-key';
+  const exampleAPIHeaderValue = 'some api key'; // base64 of 'Example-HTTP-Header-Value'
+
+  // /response-headers endpoint returns passed query params in headers
+  step('Retrieve headers from API', async() => {
+    const resp = await request.get(`${apiBaseUrl}/response-headers?${exampleAPIHeaderKey}=${exampleAPIHeaderValue}`);
+    apiKey = resp.headers()[exampleAPIHeaderKey];
+    expect(apiKey).toEqual(exampleAPIHeaderValue);
+  });
+
+  // /base64 endpoint returns the decoded string
+  step('Use API Key in HTTP request', async() => {
+    const resp = await request.get(`${apiBaseUrl}/base64/${apiKey}`);
+    decodedApiKey = await resp.text();
+    expect(decodedApiKey).toEqual('Example-HTTP-Header-Value');
+  });
+
+  // httpbin.org/headers prints all request headers
+  step('Use API Key in page request', async() => {
+    await page.setExtraHTTPHeaders({ [exampleAPIHeaderKey]: decodedApiKey });
+    await page.goto('https://httpbin.org/headers');
+    await page.waitForSelector(`text=${decodedApiKey}`);
+  });
+
+  step('Send headers to API', async () => {
+    const resp = await request.get('https://httpbin.org/headers', { headers: { 'Foo': 'Bar' } });
+    const respJson = await resp.json();
+    expect(respJson.headers['Foo']).toEqual('Bar');
+  });
+});
+-----
+
+You can also use the `request` parameter in inline journeys:
+
+[source,js]
+-----
+// The apiKey here is just a base64 of 'Example-HTTP-Header-Value'
+const apiKey = 'some api key';
+
+// We will update this from an HTTP API response
+let decodedKey;
+
+step('Retrieve API key', async () => {
+  // /base64 endpoint returns the decoded string
+  const resp = await request.get('https://httpbin.org/base64/' + apiKey);
+  decodedKey = await resp.text();
+  expect(decodedKey).toEqual('Example-HTTP-Header-Value');
+});
+
+step('Use API key', async () => {
+  await page.setExtraHTTPHeaders({ 'Example-HTTP-Header': decodedKey });
+
+  // httpbin.org/headers prints all sent headers
+  await page.goto('https://httpbin.org/headers');
+  await page.waitForSelector('text=' + decodedKey);
+});
+-----
+
 [discrete]
 [[synthetics-hb-params]]
 // lint ignore params
-== Using {heartbeat} options to set params
+== Use {heartbeat} options to set params
 
 When running via {heartbeat} use the `params` option to set additional parameters, passed through the `--params` flag
 mentioned above and have their values merged over any default values. In the example below we run the `todos` app, overriding the `url`