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

# Wait tokens

> Pause a run until a person or another system answers.

A wait token is a one-time callback URL. A run waits on it; whoever holds the
URL completes it, and the run carries on with the data they sent.

## Wait in a workflow

```ts theme={null}
import { defineWorkflow, waitForToken } from "@duraton/sdk";
import { createClient } from "@duraton/sdk/client";

const client = createClient({ url, apiKey: process.env.DURATON_SECRET_KEY ?? "" });

export const approveRefund = defineWorkflow<{ orderId: string }>({
  name: "approve-refund",
  triggers: [{ event: "refund/requested" }],
  handler: async ({ step }) => {
    const token = await step.run("create-token", () =>
      client.tokens.create({ timeoutSeconds: 3600 }),
    );
    await step.run("ask-approver", () => sendApprovalLink(token.callbackUrl));

    const answer = await waitForToken(step, token.id, { timeout: "1h" });
    if (!answer.ok) return "timed out";
    return answer.data;
  },
});
```

Create the token inside `step.run`, so a replay keeps the same one.
`waitForToken` answers `{ ok: true, data }` once the token is completed and
`{ ok: false, reason: "timeout" }` when the wait times out; a timeout is not an
error.

## Create and complete

`POST /tokens { timeoutSeconds, data?, runId? }` answers the token with a
`callbackUrl`, shown once. Anyone holding that URL completes the token with
`POST <callbackUrl> { data }`, no key; a `GET` is refused, so a link preview
never completes one. A second completion is `409 token_not_waiting`.

With a secret key you can also complete it by id:
`client.tokens.complete(id, data)`, or `POST /tokens/{id}/complete`.
`GET /tokens` and `GET /tokens/{id}` read them; a token's callback URL is never
shown again.

## Linked to its run

Every token answer carries `runId`: the run the token was made for, or `null`.
`client.tokens.create` called in workflow code (as in the step above) sends
the current run's id, so the token is linked to that run; called anywhere
else, it sends none. Pass `runId` to name another run of the project, or
`runId: null` to link none. A `runId` that names no run of the project is
`422 unprocessable`, and no token is made.

While workflows are turned off for the project, completing a token, by
`POST /tokens/{id}/complete` or its `callbackUrl`, is `409 workflows_suspended`
and the token stays waiting.


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