Authentication

3LC must be activated before it can write data. Activation validates a credential (an API key or a license key). Read operations do not require activation.

Activation

Activation happens automatically on import tlc from the configured credential:

• API key — provided with 3lc login, the TLC_API_KEY environment variable, or the API key file. See API Key for details.

• License key — provided with the TLC_LICENSE environment variable or the license key file; used with the 3LC Enterprise On-Prem deployment. See License Key for details.

TLC_API_KEY and TLC_LICENSE may contain either the key itself or the path of a file containing the key.

The advisory API: tlc.auth

tlc.auth is a read-only view over the current authentication state, intended for UX surfaces such as status bars, banners, and log decorators:

• tlc.auth.is_activated() — whether 3LC has been activated in this process.

• tlc.auth.would_authorize() — whether authentication is currently valid (identity intact and not expired).

• tlc.auth.current_identity() — a frozen tlc.auth.Identity snapshot of the active identity (user_id, tenant_id, auth_mode, provenance), or None.

• tlc.auth.expiry_status() — "ok", "near_expiry", "expired", or "none".

• tlc.auth.assert_activated() — raise the same error a write would raise right now.

These functions are informational, not enforcement — a write is checked independently when it happens, so an advisory result can be stale by the time a write executes. Use this API to inform users, not to guard a write path.

Troubleshooting

RuntimeError: No active AuthHandle — 3LC is not activated. Log in with 3lc login, or set TLC_API_KEY (or TLC_LICENSE for Enterprise On-Prem) in the environment; the handle is activated on first use.

A write (or tlc.auth.assert_activated()) ran before any activation happened. Activate 3LC as described under Activation.

ValueError: auth handle expired (mode=<mode>) at <timestamp> — re-activate to continue

The active handle’s lifetime ran out (the timestamp is Unix seconds) and no refresh path could renew it. Re-activate — for environment-driven activation, restart the process with a valid TLC_API_KEY / TLC_LICENSE.

WARNING: AccountService unreachable since <timestamp> (unix seconds); authentication will fail at <deadline> (unix seconds) unless connectivity is restored

The 3LC account service could not be reached while the handle needed renewal. Writes continue until the stated deadline; restore connectivity to the account service (or fix the network path to it) before then. A related warning, auth refresh failing; serving under network-slack window, indicates the same condition on a handle activated in this process.