Connect a project to LumenFlow Cloud + consume the API

info Prefer a guided experience? The dashboard ships an in-app wizard that walks the same six steps in order: open /dashboard/connect while signed in. The wizard issues the API key, copies the connect command, previews workspace.yaml, and probes /api/v1/health for you.

Two auth surfaces#

LumenFlow Cloud exposes two parallel bearer-token surfaces. Pick the one that matches what your consumer needs to do:

Workspace API keys are issued per workspace and act on its behalf. Engagement tokens are scoped to a single engagement (a curated view onto a workspace for an external consumer — your customer portal, a partner integration, an embedded dashboard).

Step 1 — Create a workspace#

Sign in at https://<your-cloud-host>/dashboard and create a workspace. Note the workspace ID (UUID) and your org ID — both show up in the workspace settings page.

Step 2 — Issue a workspace API key#

From the dashboard, hit the Regenerate API key button on the workspace settings page, or call the endpoint directly:

curl -X POST https://<your-cloud-host>/api/v1/workspaces/<workspaceId>/api-key \
  -H "Authorization: Bearer <your-dashboard-jwt>"

The response includes the plaintext key, the connect command, and the full SDK enrollment descriptor:

{
  "workspaceId": "<uuid>",
  "apiKey": "lf_xxxxxxxxxxxxxxxxxxxx",
  "orgId": "<uuid>",
  "connectCommand": "npx lumenflow cloud connect --endpoint https://<cloud-host> --org-id <orgId> --project-id <workspaceId> --token-env LUMENFLOW_CLOUD_TOKEN",
  "sdkEnrollment": {
    "contractVersion": 1,
    "runtimeModel": "governed_external_agent",
    "runtimeSource": "connected",
    "bootstrap": {
      "endpoint": "https://<cloud-host>",
      "orgId": "<orgId>",
      "projectId": "<workspaceId>",
      "tokenEnv": "LUMENFLOW_CLOUD_TOKEN",
      "workspaceConfig": {
        "endpoint": "https://<cloud-host>",
        "org_id": "<orgId>",
        "project_id": "<workspaceId>",
        "sync_interval": 30,
        "policy_mode": "tighten-only",
        "auth": { "token_env": "LUMENFLOW_CLOUD_TOKEN" }
      }
    }
  }
}

The plaintext apiKey is shown once. Store it in a secrets manager immediately. If you lose it, regenerate via the same endpoint — the previous key is invalidated within ~15 seconds on every cloud instance.

Step 3 — Connect the local project#

In the root of the project you want to govern:

export LUMENFLOW_CLOUD_TOKEN=lf_xxxxxxxxxxxxxxxxxxxx
npx lumenflow cloud connect \
  --endpoint https://<your-cloud-host> \
  --org-id <orgId> \
  --project-id <workspaceId> \
  --token-env LUMENFLOW_CLOUD_TOKEN

This writes the cloud bootstrap into your local workspace.yaml:

endpoint: https://<your-cloud-host>
org_id: <orgId>
project_id: <workspaceId>
sync_interval: 30
policy_mode: tighten-only
auth:
  token_env: LUMENFLOW_CLOUD_TOKEN

After this, your local LumenFlow runtime emits sessions, events, evidence and telemetry to:

• POST /api/v1/sessions
• POST /api/v1/events
• POST /api/v1/evidence
• POST /api/v1/telemetry

Minimum supported kernel is 5.0.0; the full-feature kernel is 5.0.3 (matches the @lumenflow/control-plane-sdk tagged-union plus per-pack conductor-sdk unions cloud expects).

Step 4 — Call the Sidekick API for actions#

With the workspace API key as bearer, hit any of the workspace-scoped endpoints. The most common is dispatching a Sidekick task:

curl -X POST https://<your-cloud-host>/api/v1/sidekick/chat \
  -H "Authorization: Bearer $LUMENFLOW_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "List today open approvals" }],
    "threadId": "<thread-uuid>"
  }'

Other workspace-scoped endpoints under /api/v1/:

• /sidekick/briefings/run — kick off an objective briefing
• /sidekick/objectives — read or update objectives
• /workspaces/<id>/jobs — list jobs
• /workspaces/<id>/knowledge — manage workspace memory
• /approvals plus /approvals/<id>/resolve — approval queue
• /agents — agent fleet
• /runtime/sessions — runtime sessions
• /memory/nodes plus /memory/sync — workspace memory

All workspace endpoints carry an X-LumenFlow-Control-Plane-SDK-Contract-Version header back so SDK clients can detect contract drift.

Step 5 — Consume the engagement-projection API (read-only, cross-project)#

The engagement-projection surface is the mission control model. You provision an engagement in cloud — a curated read-only view onto a workspace shaped for an external consumer — and issue them an engagement token. They then read from a fixed surface that the workspace admin can introspect via auto-generated OpenAPI per engagement.

# Get the OpenAPI spec for this engagement (auto-generated)
curl https://<your-cloud-host>/api/v1/engagements/<engagement-slug>/openapi.json \
  -H "Authorization: Bearer <engagement-token>"

The 13 endpoints under /api/v1/engagements/<slug>/:

Every response goes through a visibility-policy filter — the engagement owner controls what each engagement token can see; raw workspace state is never exposed without explicit projection.

Step 6 — Embed an engagement view#

For dashboards inside your own product (a customer portal, a partner console), issue a signed embed token and iframe the returned URL:

curl -X POST https://<your-cloud-host>/api/v1/engagements/<slug>/embed-token \
  -H "Authorization: Bearer <engagement-token>" \
  -H "Content-Type: application/json" \
  -d '{ "surface": "overview", "ttlSeconds": 900 }'

Response includes an embedUrl and expiresAt. The signed URL carries the visibility scope and renders LumenFlow's engagement UI inline in your product.

Step 7 — Server-to-server webhooks#

LumenFlow can push events outward when something changes — a job completes, an approval lands, an evidence record is anchored. Configure delivery targets per workspace; cloud signs each payload with HMAC so your receiver can verify provenance.

See /api/v1/engagements/<slug>/events for the canonical event catalog and the per-engagement webhook configuration UI in the dashboard.

Verifying the connection#

Once workspace.yaml is in place and your local runtime starts emitting:

• The dashboard /observe page shows the first runtime session appear within 30 seconds (the default sync_interval).
• /api/v1/health from your bootstrap returns { status: "ok", workspace: "<workspaceId>" }.
• The workspace Recent activity card surfaces the first event.

If nothing appears, check that LUMENFLOW_CLOUD_TOKEN is exported in the shell that runs the local runtime, and that the workspace API key has not been regenerated since your local workspace.yaml was written.

Auth model recap#

The workspace API key is the strongest credential — treat it like a service-account key. Engagement tokens are safer to share externally because their visibility is bounded by the engagement projection configuration.

Where to go next#

• Approval Workflows — gate risky actions behind human review
• Agent Fleet Management — manage runtime agents per workspace
• Webhook Integrations — push events outward to your own systems
• Sidekick Tools Reference — the ~33 named tools Sidekick can dispatch from chat