Worker Authentication

Worker authentication has two layers:

1. Bootstrap authentication (how a worker first proves identity to the server).
2. Runtime authorization (how external workers are continuously authorized to execute jobs).

For bootstrap authentication, two strategies are available:

Strategy	Features
API key	Pre-create each worker and provide a per-worker API key
Auto-Enrollment	Bootstrap with a shared secret; server issues and the worker caches an API key

Note

The server can support both bootstrap strategies at once, but each worker should use one strategy during initial bootstrap.

API key authentication

API key bootstrap is best when you need explicit, per-worker control. It is especially useful for workers on less-trusted networks.

External workers require a licensed deployment. Community Edition supports only the built-in worker.

Adding a new Worker involves the following two steps, as well as specific configuration:

Server Configuration

1. Create a new Worker with a name. As an option, customize the Worker ID.
2. Create a new API key on the Server, or re-use an existing API key.

Worker Configuration

Under the Worker startup settings:

3. Configure the Worker ID (LYFTDATA_WORKER_ID) and API key (LYFTDATA_WORKER_API_KEY) as per the Server configuration above.

Note

The Worker name is optional when using API key authentication.

Auto-enrollment authentication

Auto-enrollment uses a server-side shared secret to bootstrap new workers quickly. The server then issues an API key, and the worker caches that credential for subsequent restarts.

Unlike the API key strategy, you do not need to pre-create each worker or issue per-worker keys manually. Because this uses a shared secret, use it only on trusted networks.

Auto-enrollment is disabled by default.

Server (licensed deployments)

1. Sign in as an admin and enable auto-enrollment in Settings → Security.
2. Set an enrollment secret (random 32+ characters) and save. The secret is write-only.

Worker

3. Configure a worker with a name (LYFTDATA_WORKER_NAME) and the shared secret (LYFTDATA_AUTO_ENROLLMENT_KEY).
4. In most cases leave pre-issued worker identity settings unset (LYFTDATA_WORKER_ID, LYFTDATA_WORKER_API_KEY). If you need deterministic IDs, you can provide LYFTDATA_WORKER_ID during enrollment.

The Server will automatically create Worker entries for any connecting Workers using the Server Auto-Enrollment secret.

After the first successful enrollment, remove LYFTDATA_AUTO_ENROLLMENT_KEY from the worker service configuration. The worker will continue using cached credentials.

Security

Use a randomly generated value of at least 32 characters for the shared secret, for example: c3s3R0s1T5QAQr7lz1KsT00pKh3adnma.

Danger

If the Auto-Enrollment secret is known, anyone with network access to the Server can add new Workers, without having access to the Server itself.

See also: Worker Auto Enrollment for provisioning and rotation runbooks.

Runtime authorization (external workers)

After bootstrap, external workers are authorized at runtime using signed, time-bounded auth leases issued by the server and refreshed periodically.

• Built-in workers do not use auth leases.
• External workers that cannot obtain/refresh valid authorization stop running jobs.
• Community Edition does not authorize external workers.
• Lease expiry is capped at license expiry: a lease minted under a license never outlives that license.
• A still-valid lease runs to its natural expiry when the server enters Community Edition or the license lapses; the server refuses lease renewal rather than revoking valid leases.
• Since v2.0.8, a refused lease carries a specific, stable reason the worker logs and the UI shows: community_edition_no_external_workers or license_expired_or_invalid: <detail>. Use lyftdata doctor to see per-worker authorization posture and remedies.
• After activating a valid license, workers recover automatically within a few minutes (one lease-refresh cycle) — no restart needed.
• Workers older than v2.0 are not supported against v2.0.x and later servers and must be upgraded before connecting.

Runtime authorization repair

When a worker is visible as online but a deployment, Provider Pack, or MCP tool reports a worker/runtime blocker, check the runtime-requirements report before resetting the worker. That report separates worker heartbeat from the target job and setup state.

Common typed blockers:

Blocker	Meaning	Repair path
worker_auth_root_keypair_mismatch or worker_auth_root_keypair_unreadable	The server cannot safely issue worker auth key bundles.	Use worker-auth root health and trust-reset operations; then explicitly reset or re-pin affected workers.
worker_database_binding or worker_database_acl_missing	The selected worker does not expose the required worker database, or the exact rendered runtime job is not allowed to use it.	Update worker settings or apply a current runtime-requirements repair proposal.
Missing job binding or credential-scope blockers	The target runtime jobs cannot use the required credential/source binding.	Repair through Credential Manager or the setup journey flow, then rerun readiness.

Do not repair worker-auth or worker runtime state by editing SQLite files. Direct database reads can help with diagnostics, but writes bypass audit and can leave the server, worker, and readiness reports disagreeing.