Access Control

LyftData protects product and worker operations with authenticated principals, role checks, resource scope, and route-specific authorization. Use separate identities for people, automation, and workers so one unrestricted credential does not become the trust boundary for an entire deployment.

Applies to

Authenticated, role-aware access is a beta capability across Community and Enterprise single-node, distributed-worker, and hybrid deployments. Access behavior remains route-, release-, and deployment-specific; this guide is not a security certification.

Principals and credentials

The principal is the identity LyftData authorizes for a request:

Principal	Typical credential	Use
Interactive user	Signed-in session or bearer token	UI and operator actions
Automation client	API key exchanged for a bearer JWT	Bounded API and CLI workflows
External worker	Per-worker API key followed by signed, time-bounded runtime authorization	Worker registration and job execution
Allowlisted collector	Network allowlist plus the special read header	Selected worker telemetry reads only

Do not reuse worker credentials for user automation, use a shared admin token for dashboards, or treat a network allowlist as general API access.

Roles and route policy

Common user roles are:

• Viewer for supported read-only UI and API operations.
• User for normal product use and supported writes.
• Admin for configuration, identity, deployment, and other privileged operations. API keys use their own route-specific roles, such as api-read and api-write. These roles are not interchangeable with the human viewer/user/admin roles. An endpoint decides which principal family and role it accepts. Similar-looking routes can have different policies, so a role name does not grant universal access. A write endpoint may require an admin even when its corresponding list endpoint accepts a viewer.

Prefer this operating pattern:

1. Identify the exact routes or CLI commands an integration needs.
2. Start with a read-only principal.
3. Add only the required write authority.
4. Test one allowed and one denied operation.
5. Record the principal owner, expiry or rotation date, and intended scope.

A 401 Unauthorized response usually means the request did not establish a valid identity. A 403 Forbidden response means LyftData identified the principal but the route or resource scope does not allow the operation.

Tenant, environment, and platform scope

Principals can carry tenant scope, and supported resources can add environment, worker, job, or deployment scope. Platform-scoped administration is broader than tenant administration and should be reserved for platform operations.

Scope is enforced by the contract for each route and resource. Do not assume that adding a tenant_id query parameter makes an otherwise global resource tenant-isolated. For a multi-tenant design:

• verify each route used by the workflow;
• use separate credentials for unrelated tenants;
• keep environment and worker placement boundaries explicit; and
• use separate LyftData deployments when the selected release cannot enforce the isolation you require.

API keys and operator tokens

Create distinct API keys for distinct clients. Avoid a single “integration” key shared by dashboards, deployment automation, and support tooling.

An API key is bootstrap material, not the normal authorization header for product requests. Exchange it for a time-bounded JWT with the shipped CLI:

lyftdata api-key auth -

Provide the API key on standard input, capture the returned JWT in the automation secret store, and send it as Authorization: Bearer <token>. The equivalent token endpoint is POST /api/tokens/create/api.

• Give each key a clear owner and purpose.
• Apply the narrowest supported role and tenant scope.
• Store it in a secret manager, not a job context or checked-in file.
• Rotate it on a schedule and immediately after suspected exposure.
• Revoke keys for retired clients and confirm the client can no longer access the API.

See API Authentication for token handling, Security Hardening for transport and host controls, and the CLI reference for connecting to the server.

Worker authority

Worker bootstrap proves a worker identity; runtime authorization determines whether an external worker may continue executing jobs. These are separate checks.

Use one API key per worker where possible. Auto-enrollment is a temporary bootstrap convenience, not a permanent shared runtime credential. External workers also refresh signed, time-bounded authorization leases. A worker that cannot refresh its lease stops running jobs.

Worker heartbeat proves connectivity only. It does not prove that a particular job has a valid deployment, required credentials, database access, or runtime capacity. Follow Worker Recovery and Serviceability when an online worker cannot serve a target job.

Allowlisted telemetry collectors

The optional server allowlist grants a deliberately narrow bypass for selected worker read endpoints when the request also sends Authorization: WHITELIST. Treat this as privileged infrastructure:

• list exact collector source addresses instead of broad networks;
• protect the server from spoofed or untrusted forwarding paths;
• expose only the intended read endpoints; and
• verify that writes and unrelated reads remain denied.

Use a normal read-only token when source addresses are not stable or the deployment cannot enforce the network boundary.

Access review checklist

• List interactive users, automation keys, worker identities, and allowlisted collectors.
• Remove identities with no current owner.
• Confirm read-only clients cannot mutate configuration or deployments.
• Confirm tenant and environment scope on the exact routes in use.
• Review worker enrollment and runtime authorization separately.
• Rotate credentials and record the result.
• Review audit and application logs for denied or unexpected access.
• Repeat the review after upgrades because route classifications can change.

Access control answers who may request an operation. It does not prove the operation is ready or that an external effect occurred. Use Runtime Evidence and Receipts for that evidence boundary.