> ## Documentation Index
> Fetch the complete documentation index at: https://intunedhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ephemeral parameters

> Pass secrets to a single Run without storing them anywhere

> [!NOTE]
>
> This feature is in **preview**. The API may change before general availability. To try it out, contact [support@intunedhq.com](mailto:support@intunedhq.com) and we'll enable it for your workspace.

## Overview

Ephemeral parameters are inputs for a single Run that Intuned never retains. You pass them alongside `parameters` when you start a Run, read them from your automation when you need them, and they're deleted—either the moment you invalidate them, or when the Run ends.

Regular `parameters` are stored on the Run record so you can see what a Run was called with, re-run it, and debug it. That's the right default for a product ID or a date range. It's the wrong default for an end user's portal password.

Intuned gives you three places to put a sensitive value. They solve different problems:

| | Scope | Retained | Use it for |
| - | - | - | - |
| [Environment variables](https://intunedhq.com/docs/main/02-features/environment-variables-secrets.md) | Project or workspace | Until you delete it | Your own API keys and service credentials |
| [AuthSessions](https://intunedhq.com/docs/main/02-features/auth-sessions.md) | Reusable across Runs | Until invalidated, revalidated by Intuned | A login Intuned should keep alive for you |
| **Ephemeral parameters** | One Run | No longer than that Run | A per-Run secret you must not keep |

## When to use them

Use ephemeral parameters when the sensitive value is **different on every Run** and **shouldn't outlive it**:

* **Credentials supplied by an end user** — Your application collects a customer's portal login and triggers a Run with it. You don't want a copy in Intuned's Run history.
* **One-time codes** — A verification code read from your own system and handed to the automation.
* **Identifiers you can't retain** — A government ID, account number, or patient identifier that your compliance posture says must not be stored outside your systems.

Don't use them for:

* **A secret shared by every Run** — Use [environment variables](https://intunedhq.com/docs/main/02-features/environment-variables-secrets.md).
* **A login you want Intuned to maintain** — Use [AuthSessions](https://intunedhq.com/docs/main/02-features/auth-sessions.md), which keep the session alive and revalidate it instead of logging in on every Run.
* **Values you need to see later** — They're gone. If you need to know what a Run was called with, it belongs in `parameters`.

## How it works

### 1. Pass them when you start the Run

Add an `ephemeralParameters` map to the Run request. Keys are strings; values are JSON scalars—string, number, or boolean. The map is one level deep; nested objects and arrays aren't accepted.

**API**

```typescript Typescript theme={null}
const result = await intuned.projects.runs.start(projectName, {
  api: "submit-claim",
  parameters: {
    claimId: "C-10294", // stored on the Run record, as usual
  },
  ephemeralParameters: {
    portalPassword: "<end-user-password>", // never stored
    memberId: 48213,
  },
});
```

```python Python theme={null}
from intuned_client import models

started_run = intuned.projects.runs.start(
  project_name=project_name,
  body=models.RunStartRequestBody(
    api="submit-claim",
    parameters={
      "claim_id": "C-10294", # stored on the Run record, as usual
    },
    ephemeral_parameters={
      "portal_password": "<end-user-password>", # never stored
      "member_id": 48213,
    },
  ),
)
```

**CLI**

> [!NOTE]
>
> Run from your project directory (where Intuned Settings is located), or specify the project explicitly with `-p <project-name>`.

Pass a file rather than an inline JSON string—an inline secret ends up in your shell history:

```bash theme={null}
intuned platform runs start @run-config.json
```

```json run-config.json theme={null}
{
  "api": "submit-claim",
  "parameters": { "claimId": "C-10294" },
  "ephemeralParameters": {
    "portalPassword": "<end-user-password>",
    "memberId": 48213
  }
}
```

> [!TIP]
>
> Delete the config file after the Run, or generate it into a temporary path. Intuned doesn't store the values, but your filesystem will.

### 2. Read them from your automation

Call `getEphemeralParameter` with the key. The helper **pauses tracing** before it hands you the value, so it can't be captured by the browser trace, a screenshot, or an automation log.

```typescript Typescript theme={null}
import {
  getEphemeralParameter,
  invalidateEphemeralParameter,
  withTracingPaused,
} from "@intuned/runtime";

await withTracingPaused(async () => {
  const password = await getEphemeralParameter("portalPassword");
  await page.getByLabel("Password").fill(String(password));
  await invalidateEphemeralParameter("portalPassword");
});

await page.getByRole("button", { name: "Sign in" }).click();
```

```python Python theme={null}
from intuned_runtime import (
    get_ephemeral_parameter,
    invalidate_ephemeral_parameter,
    tracing_paused,
)

async with tracing_paused():
    password = await get_ephemeral_parameter("portal_password")
    await page.get_by_label("Password").fill(str(password))
    await invalidate_ephemeral_parameter("portal_password")

await page.get_by_role("button", name="Sign in").click()
```

Reading a key that wasn't passed—or was already invalidated—returns `undefined` in TypeScript and `None` in Python. It doesn't throw.

> [!NOTE]
>
> `getEphemeralParameter` pauses tracing but doesn't resume it. Use the scoped form above, or call `resumeTracing` / `resume_tracing` yourself once you're done. Otherwise the rest of the attempt goes unrecorded. See [Pause tracing](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/pause-tracing.md).

### 3. They get deleted

An ephemeral parameter is deleted in whichever of these happens first:

| Trigger | When |
| - | - |
| You invalidate it | `invalidateEphemeralParameter` returns. Immediate. |
| The Run finishes | The Run reaches `Success`, `Failed`, or `Canceled`. Covers every key you didn't invalidate. |
| TTL expires | 24 hours after the Run was created, enforced by the storage layer. Covers a Run that's never picked up. |

Invalidation is scoped to the **Run**, so every attempt shares it. If an attempt invalidates a key and then fails, the retry reads `undefined`. See [Invalidation and retries](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/ephemeral-parameters.md#invalidation-and-retries) for how to choose.

## Where the values do and don't go

Ephemeral parameters are held in a dedicated store, separate from the one that holds Run inputs and results, with tighter access controls and a hard TTL. They're encrypted at rest, readable only by the machine executing that Run, and deleted rather than archived.

They do **not** appear in:

* The Run record, or the input panel on the Run details page
* [Webhook or S3 sink](https://intunedhq.com/docs/client-apis/api-reference/sinks/overview.md) payloads
* Attempt logs or browser traces
* The Run result API response
* [`extendPayload`](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/extend-payload) payloads, unless you put them there yourself

> [!WARNING]
>
> The guarantee covers how Intuned stores the values—not what your automation does with them. These all defeat it:
>
> * Returning a value from your automation. Return values are stored on the Run record.
> * Putting a value in an error message. Error details are stored even while tracing is paused.
> * Logging a value after tracing resumes.
> * Writing a value into `extendPayload`, a [persistent store](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/persistent-store.md) entry, or an external system.

## Best practices

* **Invalidate as soon as the value has done its job**, unless you need retries to re-read it.
* **Keep the sensitive section short.** Read, use, invalidate, resume tracing—ideally within one scoped block.
* **Validate presence early.** If a required key is missing, throw [`NonRetryableError`](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/non-retryable-error). Retrying won't make it appear.
* **Don't echo values into the Run result.** Return a status, not the secret.
* **Keep secrets out of error messages**, including ones from your own validation.

## Limitations

* **Runs only.** Ephemeral parameters are accepted on the [Run start](https://intunedhq.com/docs/client-apis/api-reference/projectsruns/run-api--start.md) request. They aren't available for [Jobs](https://intunedhq.com/docs/main/02-features/jobs-batched-executions.md), whose payloads are stored and replayed on a schedule, or for [AuthSession](https://intunedhq.com/docs/main/02-features/auth-sessions.md) create and update requests.
* **Flat, scalar values.** One level of keys; string, number, or boolean values. No nested objects or arrays.
* **Not available in the Run Playground** during preview. Trigger Runs that need them via the API or CLI.
* **Write-only from Intuned's side.** Once passed, there's no API to read an ephemeral parameter back. The automation is the only consumer.
* **Not recoverable.** If a Run fails after invalidating a value, you have to start a new Run and pass the value again.

## FAQs

> **How is this different from an environment variable?**
>
> An [environment variable](https://intunedhq.com/docs/main/02-features/environment-variables-secrets.md) is one value, set once, available to every Run in the project—right for your own API keys. An ephemeral parameter is a different value per Run, supplied by the caller, and retained for no longer than that Run—right for an end user's credentials.

> **Can I use them with AuthSessions?**
>
> Not during preview. Ephemeral parameters are accepted on Run requests only, so an AuthSession's create and update parameters are still stored the way they are today. Note that `authSession.saveTrace` already defaults to `false` for this reason. If this blocks your use case, [contact support](mailto:support@intunedhq.com).

> **What happens if the Run never gets picked up?**
>
> The values are deleted by their 24-hour TTL whether or not the Run ever executes. Nothing is left behind if a Run sits queued and is then canceled.

> **Can I see which ephemeral keys a Run was given?**
>
> No. Keys aren't recorded either—only your automation knows what it asked for. If you need an audit trail, log the key names from your own system before you start the Run.

> **Do they work in local development?**
>
> Yes. `intuned dev` accepts `ephemeralParameters` in a run configuration and the runtime helpers behave the same, so you can test the flow before deploying.

## Related resources

> **[Ephemeral parameters (TypeScript)](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/ephemeral-parameters.md)**
>
> `getEphemeralParameter` and `invalidateEphemeralParameter`

> **[Ephemeral parameters (Python)](https://intunedhq.com/docs/main/05-references/runtime-sdk-python/ephemeral-parameters.md)**
>
> `get_ephemeral_parameter` and `invalidate_ephemeral_parameter`

> **[Pause tracing](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/pause-tracing.md)**
>
> Keep sensitive steps out of traces and logs

> **[Environment variables and secrets](https://intunedhq.com/docs/main/02-features/environment-variables-secrets.md)**
>
> For secrets that are the same on every Run


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.