Credentials

A credential is a secret Duraton stores on your behalf (an API key, an OAuth token, SMTP settings) so a workflow can call a third-party service without the credential living in an environment variable. client.credentials.resolve() reads one back at execution time.

Resolve inside a step

Resolution must happen inside a step.run (or step.ai.*) closure, never in the workflow handler’s top-level body. A step’s input and output are durable - they are recorded and replayed forever - so a credential resolved outside a step, then passed into one, would sit in that replayed record permanently. Resolved inside the closure, the credential is used only for the one call that needs it and is gone once the step returns:

import { createClient } from "@duraton/sdk";

const duraton = createClient({
  url: process.env.DURATON_URL!,
  apiKey: process.env.DURATON_API_KEY,
});

await ctx.step.run("publish", async () => {
  const cred = await duraton.credentials.resolve(credentialId);
  return post(cred.credential, topic);
});

resolve() called outside a step - directly in the handler body, or stashed in a variable before a step.run call - throws immediately (CredentialResolveOutsideStepError) rather than silently handing back a credential with no durable-input protection.

Field	Type	Description
`credential`	`string`	The credential’s plaintext, decoded from the wire. Duraton treats it as opaque - see the shapes below for what it holds.
`authShape`	`CredentialAuthShape`	Which shape `credential` holds.

Auth shapes

authShape tells you how to read credential and how to present it to the third party. A single-value shape is the value itself; a multi-field shape is a JSON string you parse yourself.

`authShape`	`credential` holds
`api_key`	The key itself, with no placement implied - you decide where it goes.
`header_auth`	`{"name": "X-Api-Key", "value": "..."}` - send `value` as the request header `name`.
`query_auth`	`{"name": "token", "value": "..."}` - send `value` as the URL query parameter `name`.
`basic_auth`	The credential itself.
`oauth2`	`{"access_token": "...", "refresh_token": "..."}`, written and refreshed by Duraton.
`oauth1`, `smtp`, `incoming_webhook`	Whatever you stored. Duraton defines no schema for these - the bytes are yours.

header_auth and query_auth are distinct shapes rather than an api_key with a placement setting, because placement changes how you use the credential, not just what its bytes are - so it travels in the shape rather than hidden inside the blob. A replayed step never re-invokes its body, so a memoized resolve() call never runs twice and never fails if the credential was since deleted - it only had to exist at the moment the step first ran.

Retrying a rejected credential

Duraton refreshes an OAuth credential’s access token ahead of its known expiry, so a normal resolve already returns a live token. A token can still be rejected by the provider despite looking valid (clock skew, early revocation) - catch that in the step and let the step’s own retry call resolve() again:

await ctx.step.run(
  "publish",
  async () => {
    const cred = await duraton.credentials.resolve(credentialId);
    const res = await post(cred.credential, topic);
    if (res.status === 401) throw new Error("credential rejected, retrying");
    return res;
  },
  { retry: { maxAttempts: 2 } },
);

The second attempt calls resolve() again from scratch, picking up a refreshed token if one is due. A token rejected well before its known expiry (the provider revoked access early) is not fixed by a retry - the credential needs re-authorization; see Retries & failure handling for NonRetriableError to fail fast on that case instead of spending the retry budget.

Start with code

Agent kit

AI

Durable runs

Integrations

TypeScript SDK

REST API

Protocol

Resolve inside a step

Auth shapes

Retrying a rejected credential

​Resolve inside a step

​Auth shapes

​Retrying a rejected credential

Resolve inside a step

Auth shapes

Retrying a rejected credential