Telemetry keys

Every Flowstate Agent authenticates to the cloud proxy at ai.flowstate.inc with a key set by your administrator. There are two key shapes in production today:

Shape	Where it lives	Used by
Org-scope composite key	One per organisation, issued at Settings → AI → Cloud Proxy (direct link)	The Flowstate Agent (v1.12+) talking to the cloud proxy.
Per-user legacy telemetry key	One per employee or contractor, issued at the deprecated Settings → AI → Telemetry Keys page	Older direct-to-collector deployments and any custom OTLP exporters that have not been migrated to the cloud proxy yet.

New deployments should use the org-scope composite key exclusively. Per-user telemetry keys are kept for backward compatibility while customers migrate; the legacy page surfaces a deprecation banner in the UI.

Org-scope composite key (the one you want today)

The org-scope key is a single string of the form

base64(tenantSlug:apiKey)

— your tenant slug paired with an API token, base64-encoded. The cloud proxy at ai.flowstate.inc accepts it as HTTP Basic Auth on every forwarded request: it decodes the value, splits on : to recover the tenant slug and the API token, validates the token against your organisation, and routes the captured traffic into your tenant.

You only ever see, paste, or rotate the composite — the agent never reads the slug and the API token separately.

Provision one

1. Go to https://app.flowstate.inc/settings/ai/cloud-proxy.
2. Click Provision org key.
3. Copy the composite string. It is shown in full once on creation and is not retrievable afterwards. Lose it → issue a new one.
4. Paste it into the MDM secret referenced by the Cloud Proxy payload.

The same key embeds in every machine in the fleet. The agent additionally sends a per-device FLOWSTATE_USER (the engineer's email) so the cloud proxy can attribute sessions to people without you needing a separate key per engineer.

Rotate one

In the same UI: Re-provision (rotate). The new key is shown once and the previous active org key is revoked by the same operation. Update your MDM secret store, then force a device sync.

There is no enforced rotation cadence. We recommend rotating when:

• Your internal compliance posture calls for an annual rotation.
• A device is lost or wiped and you want to invalidate any cached credential. (Note: revoking the device's key alone isn't enough if every device shares the org key — you also have to remove the key from the device's /etc/flowstate.env or the registry. The agent's local flowstate uninstall handles that cleanly.)
• A key is leaked (committed to a repo, posted in Slack, screenshotted in a ticket).

Legacy per-user telemetry keys

For organisations that have not yet migrated to the cloud-proxy path, the old per-user telemetry key model is still supported. Each employee or contractor gets their own key; the agent emits OpenTelemetry directly to the collector at otel.flowstate.inc rather than going through the cloud proxy.

This pattern predates the cloud proxy. Its drawbacks:

• One key per person → more secrets to provision, rotate, and revoke.
• The agent's data lands pre-attributed, but the rest of Flowstate's attribution stack still has to resolve the per-user key back to an identity, which is one extra hop compared to the cloud-proxy path.
• The legacy page is deprecated and will be removed in a future release.

If you're starting fresh, use the org-scope composite key. If you already have per-user keys, you don't need to do anything urgent — but plan to migrate before your next renewal.

Migrating from per-user to org-scope

1. Provision an org-scope key at https://app.flowstate.inc/settings/ai/cloud-proxy.
2. Roll out the new key across the fleet via your MDM as FLOWSTATE_OTLP_KEY, alongside FLOWSTATE_USER (engineer email) and FLOWSTATE_MODE=cloud-proxy.
3. Once the fleet is on the org-scope key (you can see this in the per-device sessions view in Flowstate — sessions stop arriving via the legacy collector and start arriving via the cloud proxy), revoke the per-user keys.
4. The legacy Settings → AI → Telemetry Keys page can be ignored once migration is complete.

How the agent reads the key

The agent reads FLOWSTATE_OTLP_KEY from the environment in this precedence order (highest wins):

1. Local env var — set inline for one-off debugging.
2. Per-platform managed config — /etc/flowstate.env (macOS / Linux), HKLM\SOFTWARE\Flowstate\Agent\FLOWSTATE_OTLP_KEY (Windows).
3. Built-in default — there isn't one; the agent refuses to start if no key is set.

For full precedence rules across every variable, see environment variables.

Programmatic management

The same surface is available via the API for organisations that want to manage keys from their identity provisioning pipeline — endpoints for issue, rotate, revoke, and list. See the API reference.