Skip to content

docs(relayflows): lead FLOWS_CLOUD_TOKEN with the dashboard, not CLI login #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
khaliqgant merged 2 commits into from
Sep 11, 2026
Merged

docs(relayflows): lead FLOWS_CLOUD_TOKEN with the dashboard, not CLI login #67

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a24de2
docs(relayflows): lead FLOWS_CLOUD_TOKEN with the dashboard, not CLI …
khaliqgant Sep 11, 2026
3c61e62
docs(relayflows): make the FLOWS_CLOUD_TOKEN placeholder unmistakable
khaliqgant Sep 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 8 additions & 10 deletions web/content/docs/relayflows/cloud.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, replacing the placeholder below with what you copied:

```bash
export FLOWS_CLOUD_TOKEN="$(agent-relay cloud session --json --reveal-token | jq -r .accessToken)"
export FLOWS_CLOUD_TOKEN="cld_at_paste-your-copied-token-here"
```

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.

Expand Down
Loading