Brainforge Knowledge

openwork-labs-access-policy

2 min read

OpenWork Labs Access Policy + Usage Logging Setup

Use this guide when deploying hosted OpenWork Labs (for example labs.brainforge.ai) and you need an internal-only access gate with auditable usage logs.

What this setup does

  • Enforces a shared access gate before non-health OpenWork routes can be used.
  • Keeps health checks open (/health, /w/:id/health) for deployment liveness probes.
  • Emits request logs with access and actor metadata for internal rollout tracking.

This is intentionally a lightweight, reversible policy for pre-public rollout.

Required environment variables

Set on the OpenWork host service:

  • OPENWORK_LABS_ACCESS_TOKEN (required to enable the gate)
  • OPENWORK_TOKEN (existing OpenWork API bearer token)
  • OPENWORK_HOST_TOKEN (existing owner/admin token)

Recommended:

  • OPENWORK_LOG_FORMAT=json
  • OPENWORK_LOG_REQUESTS=true

Optional tuning:

  • OPENWORK_LABS_ACCESS_COOKIE_NAME (default openwork_labs_access)
  • OPENWORK_LABS_ACCESS_LOGIN_PATH (default /labs-access)
  • OPENWORK_LABS_ACCESS_QUERY_PARAM (default labs_access_token)
  • OPENWORK_LABS_ACCESS_COOKIE_MAX_AGE_SECONDS (default 43200, max 2592000)

Access flow

When OPENWORK_LABS_ACCESS_TOKEN is set:

  1. Browser users are redirected to /labs-access and submit the token once.
  2. Server sets an HttpOnly cookie and redirects back.
  3. API/script users can send X-OpenWork-Access-Token: <token> instead of using the form.
  4. Bootstrap links can use ?labs_access_token=<token> once; server converts it into a cookie and removes the query param.

Unauthenticated API requests return:

{ "code": "labs_access_required", "message": "Labs access token required" }

Rotation + recovery runbook

Rotate the Labs access token

  1. Generate a new token (1Password item or secure random generator).
  2. Update OPENWORK_LABS_ACCESS_TOKEN in deployment env.
  3. Redeploy/restart the OpenWork host service.
  4. Share the new token with internal users through approved internal channel.

Result: existing Labs access cookies are immediately invalid after restart because they contain the old token.

Recover access

If a user is locked out:

  1. Send them the current Labs token.
  2. Ask them to open https://labs.brainforge.ai/labs-access.
  3. Submit token, then retry https://labs.brainforge.ai/ui.

If needed, force reset by rotating OPENWORK_LABS_ACCESS_TOKEN again.

Inspect usage logs after test sessions

With OPENWORK_LOG_FORMAT=json, filter host logs by:

  • labs.access.policy_enabled
  • labs.access.source
  • labs.access.cookie_issued
  • actor.type, actor.scope, actor.client_id, actor.token_hash
  • client.ip, client.user_agent

Example (local/container):

docker compose logs openwork-host | rg "labs\\.access|actor\\.|client\\."

Example (Railway):

railway logs --service <service-name> | rg "labs\\.access|actor\\.|client\\."

Security notes

  • Do not commit real token values.
  • Keep the Labs token distinct from OPENWORK_TOKEN to avoid exposing API auth semantics as the rollout gate.
  • Prefer passing token by login form or header; avoid persistent sharing of tokenized URLs.

Graph View

Backlinks