From 7a24de2e695526cf89f38950a7ef32a6c1834ed7 Mon Sep 17 00:00:00 2001 From: Khaliq Date: Fri, 11 Sep 2026 14:14:24 +0200 Subject: [PATCH 1/2] docs(relayflows): lead FLOWS_CLOUD_TOKEN with the dashboard, not CLI login AgentWorkforce/cloud#3549 added a self-serve 'Relayflows Cloud token' purpose to the dashboard's Workspace API tokens card, mirroring how deployment tokens and Relayfile agent keys are already provisioned there. Rewrite this section to lead with that (Settings > Workspace API tokens > purpose: Relayflows Cloud token), scoped to exactly workflow:invoke:read/write + workflow:runs:read/logs:read. agent-relay cloud login stays as a documented alternative for headless/SSH hosts with no browser to click through, but is no longer the primary/only path. Verified: $ npx tsc --noEmit # exit 0 $ npm run build # exit 0 Co-authored-by: Cursor --- web/content/docs/relayflows/cloud.mdx | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/web/content/docs/relayflows/cloud.mdx b/web/content/docs/relayflows/cloud.mdx index 4ebfbea8..bd2e6671 100644 --- a/web/content/docs/relayflows/cloud.mdx +++ b/web/content/docs/relayflows/cloud.mdx @@ -29,22 +29,20 @@ const finished = await waitForCloudFlowRun(accepted.runId); console.log(finished.status, finished.completionReason); ``` -`FLOWS_CLOUD_TOKEN` needs a Cloud API token; the `flows` CLI never logs in for you. Get one with the `agent-relay` CLI, a separate tool from `flows`: +`FLOWS_CLOUD_TOKEN` needs a Cloud API token; the `flows` CLI never logs in for you. Provision one from the [Cloud dashboard](https://cloud.agentrelay.com/dashboard/settings), the same place you'd create a deployment token or a Relayfile agent key: -```bash -agent-relay cloud login # opens a browser; add --device on a headless/SSH host -agent-relay cloud session --json --reveal-token -``` - -`session --json --reveal-token` prints the session as JSON, including the real `accessToken` (masked without `--reveal-token`, the same convention as `agent-relay workspace key`). Export that value: +1. Open **Settings → Workspace API tokens**. +2. Under **Purpose**, pick **Relayflows Cloud token**. +3. Name it, set an expiry, and create it. +4. Copy the one-time `cld_at_...` value — it's shown once — and export it: ```bash -export FLOWS_CLOUD_TOKEN="$(agent-relay cloud session --json --reveal-token | jq -r .accessToken)" +export FLOWS_CLOUD_TOKEN="cld_at_..." ``` -This token carries a `cli:auth` scope, not the literal `workflow:invoke:write` / `workflow:runs:read` strings — but Cloud's workflow-run endpoints accept `cli:auth` for both submitting and polling a run, so it works for everything on this page. It's tied to your own login and one Cloud workspace; anyone with their own Cloud account can mint their own this way, no special access needed. +This mints a token scoped to exactly `workflow:invoke:read`, `workflow:invoke:write`, `workflow:runs:read`, and `workflow:logs:read` — nothing else — which covers both submitting and polling a run on this page. It's a workspace-level credential: anyone with dashboard access to the workspace can create or revoke one, no CLI or special access needed. -A separate, narrower-scoped token — one that literally carries only `workflow:invoke:write` and `workflow:runs:read`, nothing else `cli:auth` would also unlock — exists for unattended CI and requires direct database access to mint (`cloud`'s `npm run mint-ci-token` with `CI_TOKEN_PROFILE=workflow-invoke`; see that repo's `docs/runbooks/relay-ci-workflow-credential.md`). That path is for Agent Relay's own CI, not something a typical `flows` user needs — `agent-relay cloud login` above is the one to use. +Prefer a CLI instead (headless/SSH host, no browser to click through)? `agent-relay cloud login` (`--device` for headless) plus `agent-relay cloud session --json --reveal-token` gets you a token too, though that one carries a broader `cli:auth` scope rather than the four scopes above — Cloud's workflow-run endpoints accept either. `FLOWS_CLOUD_URL` points at a different Cloud deployment if you're not using the default. From 3c61e62090481e4ba79cdb44f3bfccd584294e15 Mon Sep 17 00:00:00 2001 From: Khaliq Date: Fri, 11 Sep 2026 14:28:20 +0200 Subject: [PATCH 2/2] docs(relayflows): make the FLOWS_CLOUD_TOKEN placeholder unmistakable Per CodeRabbit on this PR: a bare cld_at_... in the export command reads like a copy-pasteable literal. Make it explicit this is a placeholder to replace with the copied token. Co-authored-by: Cursor --- web/content/docs/relayflows/cloud.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/web/content/docs/relayflows/cloud.mdx b/web/content/docs/relayflows/cloud.mdx index bd2e6671..31c147ea 100644 --- a/web/content/docs/relayflows/cloud.mdx +++ b/web/content/docs/relayflows/cloud.mdx @@ -34,10 +34,10 @@ console.log(finished.status, finished.completionReason); 1. Open **Settings → Workspace API tokens**. 2. Under **Purpose**, pick **Relayflows Cloud token**. 3. Name it, set an expiry, and create it. -4. Copy the one-time `cld_at_...` value — it's shown once — and export it: +4. Copy the one-time `cld_at_...` value — it's shown once — and export it, replacing the placeholder below with what you copied: ```bash -export FLOWS_CLOUD_TOKEN="cld_at_..." +export FLOWS_CLOUD_TOKEN="cld_at_paste-your-copied-token-here" ``` This mints a token scoped to exactly `workflow:invoke:read`, `workflow:invoke:write`, `workflow:runs:read`, and `workflow:logs:read` — nothing else — which covers both submitting and polling a run on this page. It's a workspace-level credential: anyone with dashboard access to the workspace can create or revoke one, no CLI or special access needed.