fix(auth): honor APIFY_TOKEN env var over stored login token

[l2ysho]

What

Makes the APIFY_TOKEN environment variable take precedence over the token stored by apify login. It was being silently ignored, so:

• APIFY_TOKEN=<customer_token> apify run failed with ApifyApiError: Insufficient permissions for the Actor run.
• APIFY_TOKEN=<customer_token> apify actors ls returned Actors from the logged-in account, not the token's account.

Why

Two independent causes produced the same symptom:

1. resolveToken (src/lib/utils.ts) — the single choke point behind getLoggedClient / getApifyClientOptions (~50 commands) resolved only an explicitly-passed token, then fell straight through to the stored token. It never consulted process.env.APIFY_TOKEN. This gap is longstanding (predates the keyring refactor, which faithfully preserved it).

2. apify run (src/commands/run.ts) — the stored token was injected into the child env after process.env ({ ...process.env, ...localEnvVars }), overwriting an inherited APIFY_TOKEN. The merge order was intentionally flipped in fix: prevent modifying local input.json file #1042 so the CLI's input-key redirect vars win over inherited ones; that flip also caught the token as collateral damage.

Change

Precedence is now, everywhere: explicit --token arg → APIFY_TOKEN env var → stored login token.

• resolveToken returns process.env.APIFY_TOKEN before falling back to the stored token.
• apify run only injects the stored token when APIFY_TOKEN isn't already inherited — leaving fix: prevent modifying local input.json file #1042's input-key redirect behavior fully intact.

Tests

• Local unit tests (test/local/lib/credentials.test.ts) — precedence at getApifyClientOptions: env var wins over stored, explicit arg wins over env var, stored token used when neither is set.
• [api] regression test (test/local/commands/run.test.ts) — sets an inherited APIFY_TOKEN distinct from the stored token and asserts the spawned Actor sees the inherited one.

Reviewer notes

• The keyring work (feat(auth): use os keyring for secure credential storage #1148) is unrelated — it changed where secrets are stored, not the precedence. The apify run regression traces specifically to fix: prevent modifying local input.json file #1042 (2026-04-28).
• apify run still sources proxy / userId from the stored account; only the token honors the env override. Out of scope for this fix (the reported bug is token-only).

🤖 Generated with Claude Code

[DaveHanns]

APIFY_TOKEN now silently overwrites the stored apify login credentials

The read-side precedence added here is correct, but this line has a downstream side effect that I think makes it a blocker.

Because resolveToken() now returns process.env.APIFY_TOKEN, getLoggedClient(), reached by ~all authenticated commands via getLoggedClientOrThrow(), then persists it:

// src/lib/utils.ts, getLoggedClient()
const resolvedToken = await resolveToken(token);          // ← now the APIFY_TOKEN value
…
if (apifyClient.token) {
    await setToken(apifyClient.token, { skipIfUnchanged: true });   // ← writes it to keyring/auth.json
}
…
writeFileSync(AUTH_FILE_PATH(), JSON.stringify({ ...existingFile, ...userInfo }));  // ← rewrites username/id too

setToken(…, { skipIfUnchanged: true }) writes whenever the value differs from what's stored. Pre-PR, resolvedToken was always the stored token, so this was a no-op. Now:

apify login --token <A>   # stored login = account A
export APIFY_TOKEN=<B>    # a different, valid token
apify actors ls           # reads B (correct) — but setToken overwrites stored A with B,
                          #   and auth.json username/id are rewritten to account B
unset APIFY_TOKEN
apify actors ls           # resolveToken → getToken() → returns B  ← login A is gone

So a transient env var permanently mutates the durable login: the apify login account is silently replaced, and the change persists after unset. Two consequences:

1. The env and stored tiers stop being independent — using APIFY_TOKEN destroys the stored login. This also contradicts the intent of the new run.ts guard's own comment ("must win over the stored login", i.e. without replacing it).
2. It re-triggers the macOS Keychain write prompt that skipIfUnchanged was added to avoid — every command run with a differing APIFY_TOKEN rewrites the keyring.

Suggested fix: in getLoggedClient, only call setToken / setProxyPassword when the token came from an explicit apify login, not when it originated from APIFY_TOKEN or --token flag of command other than apify login (the --token on other commands should be one-time overwrite as well), mirroring the guard already added in run.ts:332.

(Heads-up: if you make this change, apify auth token will then print the stored token while other commands use the env token — it reads getLocalUserInfo().token directly and only looks correct today because of this overwrite. It'd need to become env-aware too.)

🤖 Generated with Claude Code

[l2ysho]

you, this is a good catch and I am wondering how I missed this when I self reviewed 🤔

[l2ysho]

also I am inspecting getLoggedClient() and there are few things I really do not like (for example it is doing mutations but name suggests it is only get), I will create a follow up issue if I find it is worth of it.

[DaveHanns]

BTW, noticed the stale name of getApifyTokenFromEnvOrAuthFile. It no longer gets the token just from Auth file, but by default from keyring. We should simplify and correct the name.

[DaveHanns]

One possible blocker, otherwise looks good 🚀

[l2ysho]

@vladfrangu I really want to know what is your opinion about resolveToken function. There are multiple scenarios (APIFY_TOKEN, --token, normal auth, tests) and when I fix one I break some other. On a first look It feelslike good candidate for a deep refactoring. WDYT?