Short answer: the worker uses your current Prefect settings to create a Prefect Client, then authenticates to the API using either an API key (Cloud) or optional basic auth (self‑hosted Server). Those settings come from environment variables and/or your active Prefect profile. What the worker looks at - API location:

PREFECT_API_URL

- Cloud auth:

PREFECT_API_KEY

(Bearer token) - Self-hosted API basic auth (optional):

PREFECT_API_AUTH_STRING

in the form

username:password

- Active profile selection:

--profile

on the CLI or

PREFECT_PROFILE

env var Precedence - Environment variables override values in the active profile; anything not set falls back to defaults. - To see exactly what the worker will use, run:

prefect config view --show-sources

Typical setups - Prefect Cloud

# one-time: create a Cloud profile with your key and workspace
  prefect cloud login -k <API_KEY> -w "<account_handle>/<workspace_handle>"

  # or, at runtime, just export the key (envs override profiles)
  export PREFECT_API_KEY="<API_KEY>"
  # API URL defaults to Cloud, you usually don't need to set it:
  # export PREFECT_API_URL="<https://api.prefect.cloud/api>"

  prefect worker start --pool my-pool

Docs: Connect to Cloud • Settings & Profiles - Self-hosted Prefect Server

export PREFECT_API_URL="<https://prefect.example.com/api>"

  # Only if you have API basic auth enabled on your server:
  export PREFECT_API_AUTH_STRING="admin:supersecret"

  # If you previously set a Cloud API key in your environment, unset it
  # so the client does not try to use Cloud auth against your Server:
  unset PREFECT_API_KEY

  prefect worker start --pool my-pool

Docs: Security settings (API auth) Notes - Workers must point at the same API (and, for Cloud, workspace) that hosts the work pool you pass to

--pool

. - If both

PREFECT_API_KEY

and

PREFECT_API_AUTH_STRING

are set, the API key will be used; unset the key when targeting a self‑hosted Server with basic auth. - If you see 401/403 errors, run

prefect config view --show-sources

to confirm which values are being picked up. Are you using Prefect Cloud or a self‑hosted Prefect Server? I can tailor the exact steps for your environment.

Great question. Short version: the worker uses the same auth scheme for the events WebSocket as it does for normal HTTP requests. During the WebSocket handshake, it sends an Authorization header derived from your current Prefect settings. What gets sent - Prefect Cloud - Header:

Authorization: Bearer <PREFECT_API_KEY>

- The WS URL is derived from your API URL (https → wss), and is workspace‑scoped via the path. - Self‑hosted Prefect Server - If you’ve enabled API basic auth on your server and set

PREFECT_API_AUTH_STRING="username:password"

, the worker sends: - Header:

Authorization: Basic <base64(username:password)>

- If basic auth is not enabled, no auth header is sent for WS (same as HTTP). There are no token query parameters added; it’s header-based. How it’s wired up - Internally, the worker uses Prefect’s events clients to derive the WS URL from

PREFECT_API_URL

and attach the appropriate

Authorization

header from

PREFECT_API_KEY

(Cloud) or

PREFECT_API_AUTH_STRING

(Server). - Environment variables override profile values, so the headers reflect whatever the worker process actually has in its env. Quick conceptual example

# Cloud
headers = {"Authorization": f"Bearer {os.environ['PREFECT_API_KEY']}"}

# Self-hosted with basic auth enabled
headers = {"Authorization": "Basic " + base64.b64encode(b"admin:supersecret").decode()}

Troubleshooting tip - If you’re seeing 401s on the WS, make sure any reverse proxy/load balancer in front of your API passes the Authorization header on WebSocket upgrade requests. Also verify what the worker is picking up:

prefect config view --show-sources

Docs - Settings & Profiles - Security settings (API auth) If you can share whether you’re on Cloud or self‑hosted (and any proxy in front), I can help pinpoint the exact header and URL your worker will use.