diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8da9660ab..e60774e8a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,6 +51,22 @@ export APIFY_CONSOLE_URL=http://localhost:3000
 
 Note that if `APIFY_CONSOLE_URL` points at `localhost`, `apify login` validates your token against `http://localhost:3333`. All other commands still call the production API at `https://api.apify.com`.
 
+### `APIFY_CLI_OAUTH_ISSUER_URL`
+
+The OAuth 2.0 authorization server `apify login` talks to. The CLI fetches its RFC 8414 metadata from `<issuer>/.well-known/oauth-authorization-server` and uses the device authorization, authorization and token endpoints it lists.
+
+The default value is `https://console-backend.apify.com`.
+
+### `APIFY_CLI_OAUTH_CLIENT_ID`
+
+The OAuth 2.0 client ID of the CLI. It is the URL of a hosted client metadata document describing the CLI as a public native client.
+
+The default value is `https://apify.com/.well-known/oauth-clients/apify-cli.json`. To test against a differently hosted document, for example a key-value store record, point the variable at its URL:
+
+```bash
+export APIFY_CLI_OAUTH_CLIENT_ID='https://api.apify.com/v2/key-value-stores/<store-id>/records/oidc.json?signature=<signature>'
+```
+
 ## Code style
 
 The repo uses three tools, wired together via a pre-commit hook (`husky` + `lint-staged`):
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 60b0dadf2..a7a8fd2b3 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -72,10 +72,13 @@ To log in, run:
 apify login
 ```
 
-You can then choose one of the following methods:
+The CLI opens Apify Console in your browser, where you confirm the login. If the browser does not open, visit the printed URL and enter the code shown in your terminal.
 
-- _(Recommended)_ Sign in through the Apify Console in your browser.
-- Provide an [Apify API token](https://console.apify.com/settings/integrations).
+To use an [Apify API token](https://console.apify.com/settings/integrations) instead, pass it directly:
+
+```bash
+apify login --token <your-api-token>
+```
 
 ### Push your Actor to Apify
 
diff --git a/docs/reference.md b/docs/reference.md
index c4591a868..cb330de5f 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -160,14 +160,19 @@ DESCRIPTION
   '~/.apify/auth.json'.
   All other commands use these stored credentials.
 
-  Run 'apify logout' to remove authentication.
+  By default, the login is confirmed in Apify Console in your browser by putting
+   in a code. Run 'apify logout' to remove authentication.
 
 USAGE
-  $ apify auth login [-m console|manual] [-t <value>]
+  $ apify auth login [-m oauth2|console|manual] [-t <value>]
 
 FLAGS
-  -m, --method=<option>  Method of logging in to Apify.
-                         <options: console|manual>
+  -m, --method=<option>  Method of logging in to Apify. The
+                         default method ('oauth2') confirms the login in Apify
+                         Console by putting in a code. The 'manual' method prompts
+                         for an API token. The 'console' method uses the legacy
+                         Console hand-off, which is deprecated.
+                         <options: oauth2|console|manual>
   -t, --token=<value>    Apify API token.
 ```
 
@@ -188,6 +193,8 @@ USAGE
 ```sh
 DESCRIPTION
   Prints the current API token for the Apify CLI.
+  Tokens issued by an OAuth login expire after about an hour; the expiry is 
+  noted on stderr.
 
 USAGE
   $ apify auth token
diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 4634b988a..2de974a78 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -14,7 +14,7 @@ Many commands prompt when run interactively. To run without prompts, pass every
 - `apify create <name> --template <template>` — skip the create wizard.
 - `apify init <name>` — skip the init prompt.
 - `-y` / `--yes` on destructive commands (`apify actors rm`, etc.) — auto-confirm.
-- `apify login --token <token>` — log in without the interactive token prompt.
+- `apify login --token <token>` — log in without the browser confirmation.
 
 If a command's help shows an "interactive note", it lists exactly which flags make it non-interactive.
 
@@ -22,7 +22,7 @@ If a command's help shows an "interactive note", it lists exactly which flags ma
 
 See https://apify.com/auth.md for how to authenticate. Do not assume `APIFY_TOKEN` is already set in the environment and use it implicitly — confirm with the user first.
 
-- Persist a session explicitly: `apify login --token <token>`.
+- Persist a session explicitly: `apify login --token <token>` (plain `apify login` opens a browser confirmation, which agents cannot complete).
 - Verify auth: `apify info` (prints the logged-in user; non-zero exit / error if not authenticated).
 - Print the stored token: `apify auth token`.
 
diff --git a/src/commands/auth/login.ts b/src/commands/auth/login.ts
index d1799d1c6..94b45a5e1 100644
--- a/src/commands/auth/login.ts
+++ b/src/commands/auth/login.ts
@@ -10,14 +10,21 @@ import { cryptoRandomObjectId } from '@apify/utilities';
 import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
 import { Flags } from '../../lib/command-framework/flags.js';
 import { getConsoleIntegrationsUrl, getConsoleUrl } from '../../lib/console-url.js';
-import { AUTH_FILE_PATH } from '../../lib/consts.js';
+import { AUTH_FILE_PATH, INTERRUPT_SIGNALS } from '../../lib/consts.js';
 import { getBackend } from '../../lib/credentials.js';
 import { updateUserId } from '../../lib/hooks/telemetry/useTelemetryState.js';
 import { useMaskedInput } from '../../lib/hooks/user-confirmations/useMaskedInput.js';
-import { useSelectFromList } from '../../lib/hooks/user-confirmations/useSelectFromList.js';
+import { useSignalHandler } from '../../lib/hooks/useSignalHandler.js';
 import { createLocalApiServer } from '../../lib/local-api-server.js';
+import { loginWithAuthorizationCode } from '../../lib/oauth/authorization-code.js';
+import { getOAuthClientId, getOAuthIssuerUrl } from '../../lib/oauth/consts.js';
+import { loginWithDeviceCode } from '../../lib/oauth/device-code.js';
+import { type AuthorizationServerMetadata, fetchAuthorizationServerMetadata } from '../../lib/oauth/discovery.js';
+import { clearOAuthSession, saveOAuthSession } from '../../lib/oauth/session.js';
+import type { TokenResponse } from '../../lib/oauth/token-endpoint.js';
 import { error, info, success } from '../../lib/outputs.js';
 import { getLocalUserInfo, getLoggedClient, tildify } from '../../lib/utils.js';
+import { cliDebugPrint } from '../../lib/utils/cliDebugPrint.js';
 
 // When logging in against a local Console instance (local platform development), validate the token
 // against the local API rather than production.
@@ -26,26 +33,39 @@ const LOCAL_API_BASE_URL = 'http://localhost:3333';
 // Not really checked right now, but it might come useful if we ever need to do some breaking changes
 const API_VERSION = 'v1';
 
-const tryToLogin = async (token: string) => {
-	const apiBaseUrl = getConsoleUrl().includes('localhost') ? LOCAL_API_BASE_URL : undefined;
-	const isUserLogged = await getLoggedClient(token, apiBaseUrl);
+const getApiBaseUrlForLogin = () => (getConsoleUrl().includes('localhost') ? LOCAL_API_BASE_URL : undefined);
+
+const describeTokenLocation = async () => {
+	const backend = await getBackend();
+	if (backend === 'keyring') return 'your OS keyring';
+	if (process.env.APIFY_DISABLE_KEYRING === '1') {
+		return `${AUTH_FILE_PATH()} (OS keyring disabled via APIFY_DISABLE_KEYRING)`;
+	}
+	return `${AUTH_FILE_PATH()} (OS keyring unavailable; set APIFY_DISABLE_KEYRING=1 to silence)`;
+};
+
+const reportLoginSuccess = async ({ refreshes }: { refreshes: boolean }) => {
 	const userInfo = await getLocalUserInfo();
+	await updateUserId(userInfo.id!);
+
+	const tokenLocation = await describeTokenLocation();
+	const detail = refreshes
+		? `Your session refreshes automatically; the token is stored in ${tokenLocation}.`
+		: `Your token is stored in ${tokenLocation}.`;
+
+	success({
+		message: `You are logged in to Apify as ${userInfo.username || userInfo.id}. ${chalk.gray(detail)}`,
+	});
+};
+
+/** Logs in with a plain API token. Drops any OAuth session so stale refresh state cannot outlive the token switch. */
+const tryToLogin = async (token: string) => {
+	await clearOAuthSession();
+
+	const isUserLogged = await getLoggedClient(token, getApiBaseUrlForLogin());
 
 	if (isUserLogged) {
-		await updateUserId(userInfo.id!);
-
-		const backend = await getBackend();
-		let tokenLocation: string;
-		if (backend === 'keyring') {
-			tokenLocation = 'your OS keyring';
-		} else if (process.env.APIFY_DISABLE_KEYRING === '1') {
-			tokenLocation = `${AUTH_FILE_PATH()} (OS keyring disabled via APIFY_DISABLE_KEYRING)`;
-		} else {
-			tokenLocation = `${AUTH_FILE_PATH()} (OS keyring unavailable; set APIFY_DISABLE_KEYRING=1 to silence)`;
-		}
-		success({
-			message: `You are logged in to Apify as ${userInfo.username || userInfo.id}. ${chalk.gray(`Your token is stored in ${tokenLocation}.`)}`,
-		});
+		await reportLoginSuccess({ refreshes: false });
 	} else {
 		error({
 			message: 'Login to Apify failed, the provided API token is not valid.',
@@ -60,6 +80,7 @@ export class AuthLoginCommand extends ApifyCommand<typeof AuthLoginCommand> {
 	static override description =
 		`Authenticates your Apify account and saves credentials to '${tildify(AUTH_FILE_PATH())}'.\n` +
 		`All other commands use these stored credentials.\n\n` +
+		`By default, the login is confirmed in Apify Console in your browser by putting in a code. ` +
 		`Run 'apify logout' to remove authentication.`;
 
 	static override group = 'Authentication';
@@ -67,17 +88,29 @@ export class AuthLoginCommand extends ApifyCommand<typeof AuthLoginCommand> {
 	static override interactive = true;
 
 	static override interactiveNote =
-		'Prompts for an API token if not provided. To run non-interactively, pass --token <api-token>.';
+		'Opens Apify Console in your browser to confirm the login. To run non-interactively, pass --token <api-token>.';
 
 	static override examples = [
 		{
-			description: 'Log in interactively (prompts to choose a method, then completes the flow accordingly).',
+			description: 'Log in by confirming the request in Apify Console in your browser.',
 			command: 'apify login',
 		},
 		{
 			description: 'Log in non-interactively with an API token.',
 			command: 'apify login --token apify_api_xxxxx',
 		},
+		{
+			description: 'Log in through the legacy Apify Console hand-off.',
+			command: 'apify login --method console',
+		},
+		{
+			description: 'Type an API token into a prompt.',
+			command: 'apify login --method manual',
+		},
+		{
+			description: 'Log in on a remote machine by confirming the request in Apify Console in your browser.',
+			command: 'apify login --method oauth2',
+		},
 	];
 
 	static override docsUrl = 'https://docs.apify.com/cli/docs/reference#apify-login';
@@ -90,8 +123,9 @@ export class AuthLoginCommand extends ApifyCommand<typeof AuthLoginCommand> {
 		}),
 		method: Flags.string({
 			char: 'm',
-			description: 'Method of logging in to Apify.',
-			choices: ['console', 'manual'],
+			description: `Method of logging in to Apify. The default method ('oauth2') confirms the login in Apify Console by putting in a code. The 'manual' method prompts for an API token. The 'console' method uses the legacy Console hand-off, which is deprecated.`,
+			choices: ['oauth2', 'console', 'manual'] as const,
+			default: 'oauth2' as const,
 			required: false,
 		}),
 	};
@@ -100,103 +134,214 @@ export class AuthLoginCommand extends ApifyCommand<typeof AuthLoginCommand> {
 		const { token, method } = this.flags;
 
 		if (token) {
+			this.telemetryData.login = { method: 'token' };
 			await tryToLogin(token);
 			return;
 		}
 
-		const consoleUrl = getConsoleUrl();
-		const consoleOrigin = new URL(consoleUrl).origin;
-		const consoleIntegrationsUrl = getConsoleIntegrationsUrl();
-
-		let selectedMethod = method;
-
-		if (!method) {
-			const answer = await useSelectFromList({
-				message: 'Choose how you want to log in to Apify',
-				choices: [
-					{
-						value: 'console',
-						name: 'Through Apify Console in your default browser',
-						short: 'Through Apify Console',
-					},
-					{
-						value: 'manual',
-						name: 'Enter API token manually',
-						short: 'Manually',
-					},
-				] as const,
-				loop: true,
-			});
-
-			selectedMethod = answer;
+		switch (method) {
+			case 'manual':
+				await this.loginManually();
+				break;
+			case 'console':
+				this.telemetryData.login = { method: 'console' };
+				await this.loginViaLegacyConsole();
+				break;
+			default:
+				await this.loginViaOAuth();
 		}
+	}
 
-		if (selectedMethod === 'console') {
-			// Basic authorization via a random token, which is passed to the Apify Console,
-			// and that sends it back via the `token` query param, or `Authorization` header
-			const authToken = cryptoRandomObjectId();
-
-			const server = createLocalApiServer({
-				corsOrigin: consoleOrigin,
-				authToken,
-				routes: {
-					[`POST /api/${API_VERSION}/login-token`]: async (body, res) => {
-						try {
-							if (body.apiToken) {
-								await tryToLogin(body.apiToken);
-							} else {
-								throw new Error('Request did not contain API token');
-							}
-							res.end();
-						} catch (err) {
-							const errorMessage = `Login to Apify failed with error: ${(err as Error).message}`;
-							error({ message: errorMessage });
-							res.status(500);
-							res.send(errorMessage);
-						}
-						server.close();
-					},
-					[`POST /api/${API_VERSION}/exit`]: (body, res) => {
-						if (body.isWindowClosed) {
-							error({
-								message: 'Login to Apify failed, the console window was closed.',
-							});
-						} else if (body.actionCanceled) {
-							error({
-								message: 'Login to Apify failed, the action was canceled in the Apify Console.',
-							});
+	private async loginManually() {
+		this.telemetryData.login = { method: 'manual' };
+
+		console.log(`Enter your Apify API token. You can find it at ${getConsoleIntegrationsUrl()}`);
+
+		const tokenAnswer = await useMaskedInput({ message: 'token:' });
+		await tryToLogin(tokenAnswer);
+	}
+
+	private async loginViaOAuth() {
+		const issuer = getOAuthIssuerUrl();
+		const clientId = getOAuthClientId();
+
+		let metadata: AuthorizationServerMetadata;
+		try {
+			metadata = await fetchAuthorizationServerMetadata(issuer);
+		} catch (err) {
+			cliDebugPrint('oauth', 'discovery failed', err);
+			info({ message: 'OAuth login is not available for the Apify Console. Using the Console login instead.' });
+			this.telemetryData.login = { method: 'console', fellBackFrom: 'oauth2-discovery' };
+			await this.loginViaLegacyConsole();
+			return;
+		}
+
+		// Ctrl+C while waiting for the browser stops the polling and closes the loopback server. The
+		// authorization server has no cancel endpoint, so a pending device code simply lapses on its own.
+		const cancellation = new AbortController();
+		using _signalHandler = useSignalHandler({
+			signals: INTERRUPT_SIGNALS,
+			handler: () => cancellation.abort(),
+		});
+
+		this.telemetryData.login = { method: 'oauth2-device' };
+		const device = await loginWithDeviceCode({
+			metadata,
+			clientId,
+			signal: cancellation.signal,
+			onPrompt: ({ verificationUri, verificationUriComplete, userCode }) => {
+				const url = verificationUriComplete ?? verificationUri;
+
+				const messageParts = [
+					`${chalk.white('Info:')} Opening Apify Console to confirm your login...`,
+					'',
+					chalk.gray(`If the browser does not open, visit ${chalk.bold(url)} and approve the login.`),
+					'',
+					chalk.gray(`If prompted, enter the code ${chalk.reset.bold(userCode)}.`),
+					'',
+					`${chalk.white('Info:')} Waiting for you to confirm the login in your browser...`,
+				];
+
+				info({ message: messageParts.join('\n') });
+
+				// Printed above as well — a headless session, or a machine with no usable default browser, still needs it.
+				open(url).catch((err) => cliDebugPrint('oauth', 'could not open the browser', err));
+			},
+		});
+
+		if ('tokens' in device) {
+			await this.finishOAuthLogin(device.tokens, metadata, clientId);
+			return;
+		}
+
+		if ('stopReason' in device) {
+			this.reportStoppedLogin(device);
+			return;
+		}
+
+		cliDebugPrint('oauth', 'device code flow unavailable', device.reason);
+		info({ message: 'Device code login is not available. Opening the Apify Console sign-in page instead.' });
+
+		this.telemetryData.login = { method: 'oauth2-code', fellBackFrom: 'oauth2-device' };
+		const code = await loginWithAuthorizationCode({
+			metadata,
+			clientId,
+			signal: cancellation.signal,
+			onPrompt: (authorizeUrl) => {
+				info({ message: `Opening Apify Console at "${authorizeUrl}"...` });
+				open(authorizeUrl).catch((err) => cliDebugPrint('oauth', 'could not open the browser', err));
+				info({ message: 'Waiting for you to confirm the login in your browser...' });
+			},
+		});
+
+		if ('tokens' in code) {
+			await this.finishOAuthLogin(code.tokens, metadata, clientId);
+			return;
+		}
+
+		if ('stopReason' in code) {
+			this.reportStoppedLogin(code);
+			return;
+		}
+
+		cliDebugPrint('oauth', 'authorization code flow unavailable', code.reason);
+		info({ message: 'Browser login is not available. Using the Console login instead.' });
+		this.telemetryData.login = { method: 'console', fellBackFrom: 'oauth2-code' };
+		await this.loginViaLegacyConsole();
+	}
+
+	private reportStoppedLogin({ stopReason, message }: { stopReason: string; message: string }) {
+		if (stopReason === 'aborted') {
+			info({ message: 'Login cancelled.' });
+		} else {
+			error({ message });
+		}
+		process.exitCode = 1;
+	}
+
+	private async finishOAuthLogin(tokens: TokenResponse, metadata: AuthorizationServerMetadata, clientId: string) {
+		// The session goes first: if validating the token below fails half-way, the next command can still refresh.
+		await saveOAuthSession(tokens, {
+			issuer: metadata.issuer,
+			clientId,
+			tokenEndpoint: metadata.token_endpoint,
+		});
+
+		const isUserLogged = await getLoggedClient(tokens.access_token, getApiBaseUrlForLogin());
+
+		if (!isUserLogged) {
+			await clearOAuthSession();
+			error({ message: 'Login to Apify failed, the token issued by Apify Console was not accepted by the Apify API.' });
+			process.exitCode = 1;
+			return;
+		}
+
+		await reportLoginSuccess({ refreshes: true });
+	}
+
+	/** The pre-OAuth hand-off: Console pushes an API token to a loopback server started here. */
+	private async loginViaLegacyConsole() {
+		const consoleOrigin = new URL(getConsoleUrl()).origin;
+
+		// Basic authorization via a random token, which is passed to the Apify Console,
+		// and that sends it back via the `token` query param, or `Authorization` header
+		const authToken = cryptoRandomObjectId();
+
+		const server = createLocalApiServer({
+			corsOrigin: consoleOrigin,
+			authToken,
+			routes: {
+				[`POST /api/${API_VERSION}/login-token`]: async (body, res) => {
+					try {
+						if (body.apiToken) {
+							await tryToLogin(body.apiToken);
 						} else {
-							error({ message: 'Login to Apify failed.' });
+							throw new Error('Request did not contain API token');
 						}
-
 						res.end();
-						server.close();
-					},
+					} catch (err) {
+						const errorMessage = `Login to Apify failed with error: ${(err as Error).message}`;
+						error({ message: errorMessage });
+						res.status(500);
+						res.send(errorMessage);
+					}
+					server.close();
 				},
-			});
-
-			// Listening on port 0 will assign a random available port
-			server.listen(0);
-			const { port } = server.address() as AddressInfo;
-
-			const loginUrl = new URL(consoleIntegrationsUrl);
-			loginUrl.searchParams.set('localCliCommand', 'login');
-			loginUrl.searchParams.set('localCliPort', `${port}`);
-			loginUrl.searchParams.set('localCliToken', authToken);
-			loginUrl.searchParams.set('localCliApiVersion', API_VERSION);
-			try {
-				loginUrl.searchParams.set('localCliComputerName', encodeURIComponent(computerName()));
-			} catch {
-				// Ignore errors from fetching computer name as it's not critical
-			}
-
-			info({ message: `Opening Apify Console at "${loginUrl.href}"...` });
-			await open(loginUrl.href);
-		} else {
-			console.log(`Enter your Apify API token. You can find it at ${consoleIntegrationsUrl}`);
+				[`POST /api/${API_VERSION}/exit`]: (body, res) => {
+					if (body.isWindowClosed) {
+						error({
+							message: 'Login to Apify failed, the console window was closed.',
+						});
+					} else if (body.actionCanceled) {
+						error({
+							message: 'Login to Apify failed, the action was canceled in the Apify Console.',
+						});
+					} else {
+						error({ message: 'Login to Apify failed.' });
+					}
 
-			const tokenAnswer = await useMaskedInput({ message: 'token:' });
-			await tryToLogin(tokenAnswer);
+					res.end();
+					server.close();
+				},
+			},
+		});
+
+		// Listening on port 0 will assign a random available port
+		server.listen(0);
+		const { port } = server.address() as AddressInfo;
+
+		const loginUrl = new URL(getConsoleIntegrationsUrl());
+		loginUrl.searchParams.set('localCliCommand', 'login');
+		loginUrl.searchParams.set('localCliPort', `${port}`);
+		loginUrl.searchParams.set('localCliToken', authToken);
+		loginUrl.searchParams.set('localCliApiVersion', API_VERSION);
+		try {
+			loginUrl.searchParams.set('localCliComputerName', encodeURIComponent(computerName()));
+		} catch {
+			// Ignore errors from fetching computer name as it's not critical
 		}
+
+		info({ message: `Opening Apify Console at "${loginUrl.href}"...` });
+		await open(loginUrl.href);
 	}
 }
diff --git a/src/commands/auth/token.ts b/src/commands/auth/token.ts
index c2a307e88..e115c17ec 100644
--- a/src/commands/auth/token.ts
+++ b/src/commands/auth/token.ts
@@ -1,11 +1,14 @@
 import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
+import { getOAuthMetadata } from '../../lib/credentials.js';
 import { simpleLog } from '../../lib/outputs.js';
 import { getLocalUserInfo, getLoggedClientOrThrow } from '../../lib/utils.js';
 
 export class AuthTokenCommand extends ApifyCommand<typeof AuthTokenCommand> {
 	static override name = 'token' as const;
 
-	static override description = 'Prints the current API token for the Apify CLI.';
+	static override description =
+		'Prints the current API token for the Apify CLI.\n' +
+		'Tokens issued by an OAuth login expire after about an hour; the expiry is noted on stderr.';
 
 	static override examples = [
 		{
@@ -22,6 +25,11 @@ export class AuthTokenCommand extends ApifyCommand<typeof AuthTokenCommand> {
 
 		if (userInfo.token) {
 			simpleLog({ message: userInfo.token, stdout: true });
+
+			const oauth = getOAuthMetadata();
+			if (oauth) {
+				simpleLog({ message: `Note: this token expires at ${new Date(oauth.expiresAt).toISOString()}.` });
+			}
 		}
 	}
 }
diff --git a/src/commands/run.ts b/src/commands/run.ts
index 050e3e3c6..091c75f95 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -21,6 +21,7 @@ import {
 	MINIMUM_SUPPORTED_PYTHON_VERSION,
 	SUPPORTED_NODEJS_VERSION,
 } from '../lib/consts.js';
+import { getOAuthMetadata } from '../lib/credentials.js';
 import { execWithLog } from '../lib/exec.js';
 import { deleteFile } from '../lib/files.js';
 import { useActorConfig } from '../lib/hooks/useActorConfig.js';
@@ -28,6 +29,7 @@ import { ProjectLanguage, useCwdProject } from '../lib/hooks/useCwdProject.js';
 import { useModuleVersion } from '../lib/hooks/useModuleVersion.js';
 import { CRAWLEE_INPUT_KEY_ENV, resolveInputKey, TEMP_INPUT_KEY_PREFIX } from '../lib/input-key.js';
 import { getAjvValidator, getDefaultsFromInputSchema, readInputSchema } from '../lib/input_schema.js';
+import { getAccessToken } from '../lib/oauth/session.js';
 import { error, info, warning } from '../lib/outputs.js';
 import { replaceSecretsValue } from '../lib/secrets.js';
 import {
@@ -63,6 +65,27 @@ enum RunType {
 	Script = 2,
 }
 
+// An OAuth-issued token lives for an hour. The Actor process gets a token with at least this much of it
+// left; when a refresh cannot deliver that (e.g. offline), the user is told how long the run can rely on it.
+const LOCAL_RUN_MIN_TOKEN_LIFETIME_MS = 45 * 60_000;
+
+async function resolveTokenForLocalRun(storedToken: string | undefined): Promise<string | undefined> {
+	if (!storedToken || !getOAuthMetadata()) return storedToken;
+
+	const token = await getAccessToken({ minRemainingMs: LOCAL_RUN_MIN_TOKEN_LIFETIME_MS });
+
+	const remainingMs = (getOAuthMetadata()?.expiresAt ?? 0) - Date.now();
+	if (remainingMs < LOCAL_RUN_MIN_TOKEN_LIFETIME_MS) {
+		warning({
+			message:
+				`Your login session token expires in about ${Math.max(0, Math.round(remainingMs / 60_000))} minutes and could not be refreshed; ` +
+				`a local run longer than that loses Apify API access. For long runs, set the APIFY_TOKEN environment variable to an API token from Apify Console.`,
+		});
+	}
+
+	return token;
+}
+
 export class RunCommand extends ApifyCommand<typeof RunCommand> {
 	static override name = 'run' as const;
 
@@ -145,7 +168,8 @@ export class RunCommand extends ApifyCommand<typeof RunCommand> {
 	async run() {
 		const cwd = process.cwd();
 
-		const { proxy, id: userId, token } = await getLocalUserInfo();
+		const { proxy, id: userId, token: storedToken } = await getLocalUserInfo();
+		const token = await resolveTokenForLocalRun(storedToken);
 
 		const localConfigResult = await useActorConfig({ cwd });
 
diff --git a/src/lib/credentials.ts b/src/lib/credentials.ts
index f4a8e2d1d..0a486b830 100644
--- a/src/lib/credentials.ts
+++ b/src/lib/credentials.ts
@@ -9,9 +9,21 @@ import { cliDebugPrint } from './utils/cliDebugPrint.js';
 const KEYRING_SERVICE = 'com.apify.cli';
 const TOKEN_ACCOUNT = 'token';
 const PROXY_PASSWORD_ACCOUNT = 'proxy-password';
+const OAUTH_REFRESH_TOKEN_ACCOUNT = 'oauth-refresh-token';
 
 export type CredentialsBackend = 'keyring' | 'file';
 
+/** Non-secret state of an OAuth login. Lives in auth.json on both backends. */
+export interface OAuthMetadata {
+	issuer: string;
+	clientId: string;
+	tokenEndpoint: string;
+	/** Access token expiry, ms since epoch. */
+	expiresAt: number;
+	/** Refresh token expiry, ms since epoch, when the server reports one. */
+	refreshTokenExpiresAt?: number;
+}
+
 interface KeyringEntry {
 	getPassword(): string | null;
 	setPassword(password: string): void;
@@ -25,6 +37,8 @@ interface KeyringModule {
 interface StoredAuthFile {
 	token?: string;
 	proxy?: { password?: string; [k: string]: unknown };
+	/** `refreshToken` is only present on the file backend. */
+	oauth?: Partial<OAuthMetadata> & { refreshToken?: string };
 	secretsBackend?: CredentialsBackend;
 	[k: string]: unknown;
 }
@@ -216,9 +230,72 @@ export async function setProxyPassword(password: string, opts: { skipIfUnchanged
 	writeAuthFile(data);
 }
 
+export async function getOAuthRefreshToken(): Promise<string | undefined> {
+	const backend = await getBackend();
+	if (backend === 'keyring') return readKeyring(OAUTH_REFRESH_TOKEN_ACCOUNT);
+	return readAuthFile().oauth?.refreshToken;
+}
+
+export async function setOAuthRefreshToken(
+	refreshToken: string,
+	opts: { skipIfUnchanged?: boolean } = {},
+): Promise<void> {
+	const backend = await getBackend();
+	if (opts.skipIfUnchanged) {
+		const existing =
+			backend === 'keyring' ? await readKeyring(OAUTH_REFRESH_TOKEN_ACCOUNT) : readAuthFile().oauth?.refreshToken;
+		if (existing === refreshToken) return;
+	}
+
+	if (backend === 'keyring') {
+		try {
+			await writeKeyring(OAUTH_REFRESH_TOKEN_ACCOUNT, refreshToken);
+			return;
+		} catch (err) {
+			cliDebugPrint('credentials', 'keyring write failed; falling back to file', err);
+			downgradeBackendToFile();
+		}
+	}
+
+	const data = readAuthFile();
+	data.oauth = { ...data.oauth, refreshToken };
+	data.secretsBackend = 'file';
+	writeAuthFile(data);
+}
+
+/** Reads the OAuth metadata from auth.json without touching the keyring. Never returns the refresh token. */
+export function getOAuthMetadata(): OAuthMetadata | undefined {
+	const { oauth } = readAuthFile();
+	if (!oauth?.issuer || !oauth.clientId || !oauth.tokenEndpoint || typeof oauth.expiresAt !== 'number') {
+		return undefined;
+	}
+
+	const { refreshToken: _refreshToken, ...metadata } = oauth;
+	return metadata as OAuthMetadata;
+}
+
+/** Writes the OAuth metadata to auth.json, keeping an inline refresh token (file backend) in place. */
+export function setOAuthMetadata(metadata: OAuthMetadata): void {
+	const data = readAuthFile();
+	const refreshToken = data.oauth?.refreshToken;
+	data.oauth = refreshToken ? { ...metadata, refreshToken } : { ...metadata };
+	writeAuthFile(data);
+}
+
+/** Forgets the OAuth session (refresh token and metadata) while leaving the access token in place. */
+export async function clearOAuthState(): Promise<void> {
+	await deleteKeyring(OAUTH_REFRESH_TOKEN_ACCOUNT);
+
+	if (!existsSync(AUTH_FILE_PATH())) return;
+	const data = readAuthFile();
+	if (!data.oauth) return;
+	delete data.oauth;
+	writeAuthFile(data);
+}
+
 /**
- * Remove the token and proxy-password entries from the OS keyring. Always attempts the
- * keyring deletes even when the current backend is `file`, so toggling
+ * Remove the token, proxy-password and OAuth refresh-token entries from the OS keyring. Always
+ * attempts the keyring deletes even when the current backend is `file`, so toggling
  * `APIFY_DISABLE_KEYRING=1` between login and logout does not orphan entries the user
  * has no in-CLI way to discover. Plaintext secrets in `auth.json` are the caller's
  * responsibility (e.g. `logout` removes the whole file).
@@ -226,6 +303,7 @@ export async function setProxyPassword(password: string, opts: { skipIfUnchanged
 export async function clearKeyringSecrets(): Promise<void> {
 	await deleteKeyring(TOKEN_ACCOUNT);
 	await deleteKeyring(PROXY_PASSWORD_ACCOUNT);
+	await deleteKeyring(OAUTH_REFRESH_TOKEN_ACCOUNT);
 }
 
 /**
diff --git a/src/lib/hooks/telemetry/trackEvent.ts b/src/lib/hooks/telemetry/trackEvent.ts
index 3ea2d6eea..46ce0e6d4 100644
--- a/src/lib/hooks/telemetry/trackEvent.ts
+++ b/src/lib/hooks/telemetry/trackEvent.ts
@@ -43,6 +43,12 @@ interface CliCommandEvent {
 		wasCreated?: boolean;
 	};
 
+	login?: {
+		method: 'oauth2-device' | 'oauth2-code' | 'console' | 'manual' | 'token';
+		/** Set when the `oauth2` method could not run and another flow took over. */
+		fellBackFrom?: 'oauth2-discovery' | 'oauth2-device' | 'oauth2-code';
+	};
+
 	// init command
 	actorWrapper?: string;
 
diff --git a/src/lib/oauth/authorization-code.ts b/src/lib/oauth/authorization-code.ts
new file mode 100644
index 000000000..95df3b5f2
--- /dev/null
+++ b/src/lib/oauth/authorization-code.ts
@@ -0,0 +1,158 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import { AUTHORIZATION_CODE_TIMEOUT_MS, OAUTH_SCOPE } from './consts.js';
+import type { AuthorizationServerMetadata } from './discovery.js';
+import { postTokenRequest, type TokenResponse } from './token-endpoint.js';
+
+export type AuthorizationCodeLoginResult =
+	| { tokens: TokenResponse }
+	/** The server cannot run this flow; the caller should try another one. Nothing was shown to the user. */
+	| { unsupported: true; reason: string }
+	| { stopReason: 'accessDenied' | 'timedOut' | 'aborted' | 'exchangeFailed'; message: string };
+
+export interface AuthorizationCodeLoginOptions {
+	metadata: AuthorizationServerMetadata;
+	clientId: string;
+	signal?: AbortSignal;
+	/** Called with the authorize URL the user has to open. */
+	onPrompt: (authorizeUrl: string) => void | Promise<void>;
+}
+
+/** RFC 7636 §4.2: `BASE64URL(SHA256(code_verifier))`. */
+export function pkceChallengeFromVerifier(verifier: string): string {
+	return createHash('sha256').update(verifier).digest('base64url');
+}
+
+const CALLBACK_PATH = '/callback';
+
+const CALLBACK_PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>Apify CLI</title></head>
+<body style="font-family:system-ui,sans-serif;text-align:center;padding:4rem">
+<h1>You are logged in to the Apify CLI</h1><p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+
+type CallbackOutcome = { code: string } | { stopReason: 'accessDenied' | 'timedOut' | 'aborted'; message: string };
+
+/**
+ * OAuth 2.0 Authorization Code Grant with PKCE for a native app (RFC 8252): the redirect lands on a
+ * loopback HTTP server that the CLI starts on a random port.
+ */
+export async function loginWithAuthorizationCode({
+	metadata,
+	clientId,
+	signal,
+	onPrompt,
+}: AuthorizationCodeLoginOptions): Promise<AuthorizationCodeLoginResult> {
+	if (!metadata.authorization_endpoint) {
+		return { unsupported: true, reason: 'the authorization server does not advertise an authorization endpoint' };
+	}
+
+	const codeVerifier = randomBytes(32).toString('base64url');
+	const codeChallenge = pkceChallengeFromVerifier(codeVerifier);
+	const state = randomBytes(16).toString('base64url');
+
+	let resolve!: (outcome: CallbackOutcome) => void;
+	const finished = new Promise<CallbackOutcome>((resolveFinished) => {
+		resolve = resolveFinished;
+	});
+
+	const server = createServer((req, res) => {
+		res.setHeader('Connection', 'close');
+		const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+
+		if (req.method !== 'GET' || url.pathname !== CALLBACK_PATH) {
+			res.statusCode = 404;
+			res.end('Not found');
+			return;
+		}
+
+		// A mismatched state is not ours to act on: answer and keep waiting for the real redirect.
+		if (url.searchParams.get('state') !== state) {
+			res.statusCode = 400;
+			res.end('Invalid state');
+			return;
+		}
+
+		const oauthError = url.searchParams.get('error');
+		const code = url.searchParams.get('code');
+
+		if (oauthError || !code) {
+			res.statusCode = 400;
+			res.end('Login failed. You can close this tab.');
+			const description =
+				url.searchParams.get('error_description') ?? oauthError ?? 'no authorization code was returned';
+			resolve({ stopReason: 'accessDenied', message: `Login to Apify failed: ${description}.` });
+			return;
+		}
+
+		res.setHeader('Content-Type', 'text/html; charset=utf-8');
+		res.end(CALLBACK_PAGE);
+		resolve({ code });
+	});
+
+	const timer = setTimeout(
+		() =>
+			resolve({
+				stopReason: 'timedOut',
+				message: `Login to Apify did not finish within ${AUTHORIZATION_CODE_TIMEOUT_MS / 60_000} minutes.`,
+			}),
+		AUTHORIZATION_CODE_TIMEOUT_MS,
+	);
+
+	signal?.addEventListener('abort', () => resolve({ stopReason: 'aborted', message: 'Login was aborted.' }), {
+		once: true,
+	});
+
+	try {
+		await new Promise<void>((resolveListen, rejectListen) => {
+			server.once('error', rejectListen);
+			server.listen(0, '127.0.0.1', () => resolveListen());
+		});
+	} catch (err) {
+		clearTimeout(timer);
+		return { unsupported: true, reason: `could not start a loopback server: ${(err as Error).message}` };
+	}
+
+	const { port } = server.address() as AddressInfo;
+	const redirectUri = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+
+	const authorizeUrl = new URL(metadata.authorization_endpoint);
+	authorizeUrl.searchParams.set('response_type', 'code');
+	authorizeUrl.searchParams.set('client_id', clientId);
+	authorizeUrl.searchParams.set('redirect_uri', redirectUri);
+	authorizeUrl.searchParams.set('scope', OAUTH_SCOPE);
+	authorizeUrl.searchParams.set('state', state);
+	authorizeUrl.searchParams.set('code_challenge', codeChallenge);
+	authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+
+	let outcome: CallbackOutcome;
+	try {
+		await onPrompt(authorizeUrl.href);
+		outcome = await finished;
+	} finally {
+		clearTimeout(timer);
+		// `close` alone waits for the browser's keep-alive socket, which would hang the command.
+		server.closeAllConnections();
+		server.close();
+	}
+
+	if ('stopReason' in outcome) return outcome;
+
+	const exchange = await postTokenRequest(metadata.token_endpoint, {
+		grant_type: 'authorization_code',
+		code: outcome.code,
+		redirect_uri: redirectUri,
+		client_id: clientId,
+		code_verifier: codeVerifier,
+	});
+
+	if (!exchange.ok) {
+		return {
+			stopReason: 'exchangeFailed',
+			message: `Login to Apify failed, the authorization code could not be exchanged: ${exchange.error.message}`,
+		};
+	}
+
+	return { tokens: exchange.tokens };
+}
diff --git a/src/lib/oauth/consts.ts b/src/lib/oauth/consts.ts
new file mode 100644
index 000000000..a1ae60482
--- /dev/null
+++ b/src/lib/oauth/consts.ts
@@ -0,0 +1,52 @@
+import process from 'node:process';
+
+const DEFAULT_OAUTH_ISSUER_URL = 'https://console-backend.apify.com';
+
+// Client ID metadata document (draft-ietf-oauth-client-id-metadata-document): the client_id is the URL
+// of a JSON document describing this CLI as a public OAuth client.
+const DEFAULT_OAUTH_CLIENT_ID = 'https://apify.com/.well-known/oauth-clients/apify-cli.json';
+
+export const OAUTH_SCOPE = 'full_api_access';
+
+export const DEVICE_CODE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+
+/** Refresh when the access token has less than this left. */
+export const TOKEN_REFRESH_SKEW_MS = 60_000;
+
+/** Also refresh when the refresh token itself has less than this left, so the session keeps rolling. */
+export const REFRESH_TOKEN_RENEW_BEFORE_MS = 30 * 60_000;
+
+/** How long the authorization-code flow waits for the browser redirect. */
+export const AUTHORIZATION_CODE_TIMEOUT_MS = 5 * 60_000;
+
+/** Upper bound for a single HTTP request to the authorization server, so a hung connection cannot stall a command. */
+export const OAUTH_REQUEST_TIMEOUT_MS = 30_000;
+
+/** Poll cadence when the device authorization response omits `interval` (RFC 8628 §3.2). */
+export const DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;
+
+function readUrlEnv(name: string, fallback: string): string {
+	const explicit = process.env[name];
+	if (!explicit) return fallback;
+
+	const stripped = explicit.replace(/\/+$/, '');
+	if (!URL.canParse(stripped)) {
+		throw new Error(`Invalid ${name} environment variable: "${explicit}" is not a valid URL.`);
+	}
+	return stripped;
+}
+
+/** Authorization server issuer. Its RFC 8414 metadata lives at `<issuer>/.well-known/oauth-authorization-server`. */
+export function getOAuthIssuerUrl(): string {
+	return readUrlEnv('APIFY_CLI_OAUTH_ISSUER_URL', DEFAULT_OAUTH_ISSUER_URL);
+}
+
+export function getOAuthClientId(): string {
+	// The client_id URL may carry a query string (e.g. a signed key-value store record), so no slash stripping.
+	const explicit = process.env.APIFY_CLI_OAUTH_CLIENT_ID;
+	if (!explicit) return DEFAULT_OAUTH_CLIENT_ID;
+	if (!URL.canParse(explicit)) {
+		throw new Error(`Invalid APIFY_CLI_OAUTH_CLIENT_ID environment variable: "${explicit}" is not a valid URL.`);
+	}
+	return explicit;
+}
diff --git a/src/lib/oauth/device-code.ts b/src/lib/oauth/device-code.ts
new file mode 100644
index 000000000..406103c07
--- /dev/null
+++ b/src/lib/oauth/device-code.ts
@@ -0,0 +1,162 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import { APIFY_CLIENT_DEFAULT_HEADERS } from '../consts.js';
+import { cliDebugPrint } from '../utils/cliDebugPrint.js';
+import {
+	DEFAULT_DEVICE_POLL_INTERVAL_SECONDS,
+	DEVICE_CODE_GRANT_TYPE,
+	OAUTH_REQUEST_TIMEOUT_MS,
+	OAUTH_SCOPE,
+} from './consts.js';
+import type { AuthorizationServerMetadata } from './discovery.js';
+import { postTokenRequest, type TokenResponse } from './token-endpoint.js';
+
+/** RFC 8628 §3.2 device authorization response. */
+interface DeviceAuthorizationResponse {
+	device_code: string;
+	user_code: string;
+	verification_uri: string;
+	verification_uri_complete?: string;
+	expires_in: number;
+	interval?: number;
+}
+
+export interface DeviceCodePrompt {
+	verificationUri: string;
+	verificationUriComplete?: string;
+	userCode: string;
+	expiresInSeconds: number;
+}
+
+export type DeviceCodeLoginResult =
+	| { tokens: TokenResponse }
+	/** The server cannot run this flow; the caller should try another one. Nothing was shown to the user. */
+	| { unsupported: true; reason: string }
+	| { stopReason: 'accessDenied' | 'expired' | 'aborted'; message: string };
+
+export interface DeviceCodeLoginOptions {
+	metadata: AuthorizationServerMetadata;
+	clientId: string;
+	signal?: AbortSignal;
+	/** Called once the user has something to act on: the verification URL and code. */
+	onPrompt: (prompt: DeviceCodePrompt) => void | Promise<void>;
+}
+
+const requestDeviceAuthorization = async (
+	endpoint: string,
+	clientId: string,
+): Promise<{ ok: true; body: DeviceAuthorizationResponse } | { ok: false; reason: string }> => {
+	let response: Response;
+	try {
+		response = await fetch(endpoint, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/x-www-form-urlencoded',
+				Accept: 'application/json',
+				...APIFY_CLIENT_DEFAULT_HEADERS,
+			},
+			body: new URLSearchParams({ client_id: clientId, scope: OAUTH_SCOPE }),
+			signal: AbortSignal.timeout(OAUTH_REQUEST_TIMEOUT_MS),
+		});
+	} catch (err) {
+		return { ok: false, reason: `could not reach ${endpoint}: ${(err as Error).message}` };
+	}
+
+	let body: Partial<DeviceAuthorizationResponse> & { error?: string; error_description?: string } = {};
+	try {
+		body = (await response.json()) as typeof body;
+	} catch {
+		// Reported through the status code below.
+	}
+
+	if (!response.ok || !body.device_code || !body.user_code || !body.verification_uri || !body.expires_in) {
+		const detail = body.error_description ?? body.error ?? `status ${response.status}`;
+		return { ok: false, reason: `device authorization failed (${detail})` };
+	}
+
+	return { ok: true, body: body as DeviceAuthorizationResponse };
+};
+
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628). Polls the token endpoint at the cadence the server
+ * asked for — `interval` from the device authorization response, plus 5 s whenever it answers `slow_down`.
+ */
+export async function loginWithDeviceCode({
+	metadata,
+	clientId,
+	signal,
+	onPrompt,
+}: DeviceCodeLoginOptions): Promise<DeviceCodeLoginResult> {
+	if (!metadata.device_authorization_endpoint) {
+		return { unsupported: true, reason: 'the authorization server does not advertise a device authorization endpoint' };
+	}
+
+	const authorization = await requestDeviceAuthorization(metadata.device_authorization_endpoint, clientId);
+	if (!authorization.ok) {
+		return { unsupported: true, reason: authorization.reason };
+	}
+
+	const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } =
+		authorization.body;
+
+	await onPrompt({
+		verificationUri: verification_uri,
+		verificationUriComplete: verification_uri_complete,
+		userCode: user_code,
+		expiresInSeconds: expires_in,
+	});
+
+	let intervalSeconds = interval ?? DEFAULT_DEVICE_POLL_INTERVAL_SECONDS;
+	const deadline = Date.now() + expires_in * 1000;
+
+	while (Date.now() < deadline) {
+		try {
+			await sleep(intervalSeconds * 1000, undefined, { signal });
+		} catch {
+			return { stopReason: 'aborted', message: 'Login was aborted.' };
+		}
+		if (signal?.aborted) return { stopReason: 'aborted', message: 'Login was aborted.' };
+
+		let result;
+		try {
+			result = await postTokenRequest(metadata.token_endpoint, {
+				grant_type: DEVICE_CODE_GRANT_TYPE,
+				device_code,
+				client_id: clientId,
+			});
+		} catch (err) {
+			// Transient network trouble: keep polling until the code expires.
+			cliDebugPrint('oauth', 'device code poll failed', err);
+			continue;
+		}
+
+		if (result.ok) return { tokens: result.tokens };
+
+		cliDebugPrint('oauth', 'device code poll', result.error.code, `next in ${intervalSeconds}s`);
+
+		switch (result.error.code) {
+			case 'authorization_pending':
+				continue;
+			case 'slow_down':
+				intervalSeconds += 5;
+				continue;
+			case 'access_denied':
+				return {
+					stopReason: 'accessDenied',
+					message: 'Login to Apify failed, the request was denied in Apify Console.',
+				};
+			case 'expired_token':
+				return {
+					stopReason: 'expired',
+					message: 'Login to Apify failed, the device code expired before it was confirmed.',
+				};
+			default:
+				return {
+					stopReason: 'accessDenied',
+					message: `Login to Apify failed, the authorization server answered: ${result.error.message}`,
+				};
+		}
+	}
+
+	return { stopReason: 'expired', message: 'Login to Apify failed, the device code expired before it was confirmed.' };
+}
diff --git a/src/lib/oauth/discovery.ts b/src/lib/oauth/discovery.ts
new file mode 100644
index 000000000..585d66c7a
--- /dev/null
+++ b/src/lib/oauth/discovery.ts
@@ -0,0 +1,53 @@
+import { APIFY_CLIENT_DEFAULT_HEADERS } from '../consts.js';
+import { OAUTH_REQUEST_TIMEOUT_MS } from './consts.js';
+
+/** Subset of RFC 8414 authorization server metadata the CLI uses. */
+export interface AuthorizationServerMetadata {
+	issuer: string;
+	authorization_endpoint?: string;
+	device_authorization_endpoint?: string;
+	token_endpoint: string;
+	scopes_supported?: string[];
+	grant_types_supported?: string[];
+	code_challenge_methods_supported?: string[];
+}
+
+export class OAuthDiscoveryError extends Error {
+	override name = 'OAuthDiscoveryError';
+}
+
+export async function fetchAuthorizationServerMetadata(issuer: string): Promise<AuthorizationServerMetadata> {
+	const url = `${issuer}/.well-known/oauth-authorization-server`;
+
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			headers: { Accept: 'application/json', ...APIFY_CLIENT_DEFAULT_HEADERS },
+			signal: AbortSignal.timeout(OAUTH_REQUEST_TIMEOUT_MS),
+		});
+	} catch (err) {
+		throw new OAuthDiscoveryError(`Could not reach ${url}: ${(err as Error).message}`);
+	}
+
+	if (!response.ok) {
+		throw new OAuthDiscoveryError(`Fetching ${url} failed with status ${response.status}.`);
+	}
+
+	let metadata: Partial<AuthorizationServerMetadata>;
+	try {
+		metadata = (await response.json()) as Partial<AuthorizationServerMetadata>;
+	} catch {
+		throw new OAuthDiscoveryError(`${url} did not return valid JSON.`);
+	}
+
+	if (typeof metadata.token_endpoint !== 'string') {
+		throw new OAuthDiscoveryError(`${url} is missing "token_endpoint".`);
+	}
+
+	// RFC 8414 §3.3: the issuer in the document must match the one it was fetched for.
+	if (metadata.issuer !== issuer) {
+		throw new OAuthDiscoveryError(`${url} reports issuer "${metadata.issuer}", expected "${issuer}".`);
+	}
+
+	return metadata as AuthorizationServerMetadata;
+}
diff --git a/src/lib/oauth/session.ts b/src/lib/oauth/session.ts
new file mode 100644
index 000000000..2985e3296
--- /dev/null
+++ b/src/lib/oauth/session.ts
@@ -0,0 +1,251 @@
+import { closeSync, openSync, statSync, unlinkSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import { AUTH_FILE_PATH, CommandExitCodes, GLOBAL_CONFIGS_FOLDER } from '../consts.js';
+import {
+	clearOAuthState,
+	getOAuthMetadata,
+	getOAuthRefreshToken,
+	getToken,
+	type OAuthMetadata,
+	setOAuthMetadata,
+	setOAuthRefreshToken,
+	setToken,
+} from '../credentials.js';
+import { ensureApifyDirectory } from '../files.js';
+import { cliDebugPrint } from '../utils/cliDebugPrint.js';
+import { REFRESH_TOKEN_RENEW_BEFORE_MS, TOKEN_REFRESH_SKEW_MS } from './consts.js';
+import { OAuthError, refreshAccessToken, type TokenResponse } from './token-endpoint.js';
+
+const DEFAULT_EXPIRES_IN_SECONDS = 3600;
+
+// Cross-process guard for the refresh: refresh tokens rotate, so two CLIs refreshing at once would
+// invalidate each other. Best effort — a stuck lock is ignored after a short wait.
+const LOCK_FILE_NAME = 'oauth-refresh.lock';
+const LOCK_STALE_MS = 30_000;
+const LOCK_POLL_MS = 100;
+const LOCK_MAX_POLLS = 50;
+
+export class OAuthSessionExpiredError extends Error {
+	override name = 'OAuthSessionExpiredError';
+
+	constructor() {
+		super('Your Apify login session has expired. Run "apify login" to sign in again.');
+	}
+}
+
+let cached: { token: string; expiresAt: number } | undefined;
+let refreshedThisProcess = false;
+let inflightRefresh: Promise<string | undefined> | undefined;
+
+/** Test-only: forget the in-process token cache and refresh state. */
+export function __resetOAuthSessionForTests() {
+	cached = undefined;
+	refreshedThisProcess = false;
+	inflightRefresh = undefined;
+}
+
+export interface AccessTokenOptions {
+	/** Refresh when the access token has less than this left. Defaults to `TOKEN_REFRESH_SKEW_MS`. */
+	minRemainingMs?: number;
+}
+
+/**
+ * The stored access token, refreshed first when it is about to expire. Plain API-token logins have no
+ * OAuth metadata and pass straight through. Refreshes at most once per process.
+ */
+export async function getAccessToken({ minRemainingMs = TOKEN_REFRESH_SKEW_MS }: AccessTokenOptions = {}): Promise<
+	string | undefined
+> {
+	const metadata = getOAuthMetadata();
+	if (!metadata) return getToken();
+
+	const now = Date.now();
+
+	if (!needsRefresh(metadata, now, minRemainingMs)) {
+		if (cached && cached.expiresAt === metadata.expiresAt) return cached.token;
+		const token = await getToken();
+		if (token) cached = { token, expiresAt: metadata.expiresAt };
+		return token;
+	}
+
+	if (metadata.refreshTokenExpiresAt !== undefined && metadata.refreshTokenExpiresAt <= now) {
+		process.exitCode = CommandExitCodes.MissingAuth;
+		throw new OAuthSessionExpiredError();
+	}
+
+	if (refreshedThisProcess) return cached?.token ?? getToken();
+
+	inflightRefresh ??= refreshSession(metadata, minRemainingMs).finally(() => {
+		inflightRefresh = undefined;
+	});
+	return inflightRefresh;
+}
+
+/** Persists a fresh token response after login. */
+export async function saveOAuthSession(
+	tokens: TokenResponse,
+	metadata: Pick<OAuthMetadata, 'issuer' | 'clientId' | 'tokenEndpoint'>,
+): Promise<void> {
+	await persistTokens(tokens, metadata);
+}
+
+export async function clearOAuthSession(): Promise<void> {
+	await clearOAuthState();
+	cached = undefined;
+}
+
+function needsRefresh(metadata: OAuthMetadata, now: number, minRemainingMs: number): boolean {
+	if (metadata.expiresAt - now < minRemainingMs) return true;
+	return (
+		metadata.refreshTokenExpiresAt !== undefined && metadata.refreshTokenExpiresAt - now < REFRESH_TOKEN_RENEW_BEFORE_MS
+	);
+}
+
+async function refreshSession(metadata: OAuthMetadata, minRemainingMs: number): Promise<string | undefined> {
+	const releaseLock = await acquireRefreshLock();
+
+	try {
+		// Another process may have refreshed while this one waited for the lock.
+		const latest = getOAuthMetadata() ?? metadata;
+		if (!needsRefresh(latest, Date.now(), minRemainingMs)) {
+			const token = await getToken();
+			if (token) cached = { token, expiresAt: latest.expiresAt };
+			return token;
+		}
+
+		const refreshToken = await getOAuthRefreshToken();
+		if (!refreshToken) {
+			await clearOAuthSession();
+			process.exitCode = CommandExitCodes.MissingAuth;
+			throw new OAuthSessionExpiredError();
+		}
+
+		let tokens: TokenResponse;
+		try {
+			tokens = await refreshAccessToken({
+				tokenEndpoint: latest.tokenEndpoint,
+				clientId: latest.clientId,
+				refreshToken,
+			});
+		} catch (err) {
+			return handleRefreshFailure(err, latest, refreshToken);
+		}
+
+		await persistTokens(tokens, latest);
+		refreshedThisProcess = true;
+		return tokens.access_token;
+	} finally {
+		releaseLock();
+	}
+}
+
+async function handleRefreshFailure(
+	err: unknown,
+	metadata: OAuthMetadata,
+	usedRefreshToken: string,
+): Promise<string | undefined> {
+	cliDebugPrint('oauth', 'refresh failed', err);
+
+	const rejected = err instanceof OAuthError && (err.code === 'invalid_grant' || err.code === 'expired_token');
+
+	if (rejected) {
+		// A concurrent process may have rotated the refresh token first; its result is already stored.
+		const stored = await getOAuthRefreshToken();
+		if (stored && stored !== usedRefreshToken) {
+			const token = await getToken();
+			const current = getOAuthMetadata();
+			if (token && current) cached = { token, expiresAt: current.expiresAt };
+			return token;
+		}
+	}
+
+	// Refreshing happens ahead of expiry, so the stored token usually still works for this command.
+	if (Date.now() < metadata.expiresAt) {
+		return getToken();
+	}
+
+	if (rejected) {
+		await clearOAuthSession();
+		process.exitCode = CommandExitCodes.MissingAuth;
+		throw new OAuthSessionExpiredError();
+	}
+
+	throw new Error('Could not refresh your Apify session. Check your connection or run "apify login".');
+}
+
+/**
+ * Write order matters because the server rotates the refresh token: the new refresh token lands first,
+ * so a crash mid-way leaves a session the next run can still refresh.
+ */
+async function persistTokens(
+	tokens: TokenResponse,
+	metadata: Pick<OAuthMetadata, 'issuer' | 'clientId' | 'tokenEndpoint'> & Partial<OAuthMetadata>,
+): Promise<void> {
+	const now = Date.now();
+	const expiresAt = now + (tokens.expires_in ?? DEFAULT_EXPIRES_IN_SECONDS) * 1000;
+	const refreshTokenExpiresAt =
+		tokens.refresh_token_expires_in !== undefined
+			? now + tokens.refresh_token_expires_in * 1000
+			: metadata.refreshTokenExpiresAt;
+
+	if (tokens.refresh_token) {
+		await setOAuthRefreshToken(tokens.refresh_token, { skipIfUnchanged: true });
+	}
+	await setToken(tokens.access_token, { skipIfUnchanged: true });
+	setOAuthMetadata({
+		issuer: metadata.issuer,
+		clientId: metadata.clientId,
+		tokenEndpoint: metadata.tokenEndpoint,
+		expiresAt,
+		refreshTokenExpiresAt,
+	});
+
+	cached = { token: tokens.access_token, expiresAt };
+}
+
+async function acquireRefreshLock(): Promise<() => void> {
+	const lockPath = join(GLOBAL_CONFIGS_FOLDER(), LOCK_FILE_NAME);
+	const release = () => {
+		try {
+			unlinkSync(lockPath);
+		} catch {
+			// Already gone.
+		}
+	};
+	const noop = () => {};
+
+	try {
+		ensureApifyDirectory(AUTH_FILE_PATH());
+	} catch {
+		return noop;
+	}
+
+	for (let attempt = 0; attempt < LOCK_MAX_POLLS; attempt++) {
+		try {
+			const fd = openSync(lockPath, 'wx');
+			writeSync(fd, `${process.pid}`);
+			closeSync(fd);
+			return release;
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return noop;
+		}
+
+		try {
+			if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+				unlinkSync(lockPath);
+				continue;
+			}
+		} catch {
+			// Released between the failed open and the stat; retry immediately.
+			continue;
+		}
+
+		await sleep(LOCK_POLL_MS);
+	}
+
+	cliDebugPrint('oauth', 'refresh lock wait timed out; continuing without it');
+	return noop;
+}
diff --git a/src/lib/oauth/token-endpoint.ts b/src/lib/oauth/token-endpoint.ts
new file mode 100644
index 000000000..8d09b21e8
--- /dev/null
+++ b/src/lib/oauth/token-endpoint.ts
@@ -0,0 +1,77 @@
+import { APIFY_CLIENT_DEFAULT_HEADERS } from '../consts.js';
+import { OAUTH_REQUEST_TIMEOUT_MS } from './consts.js';
+
+export interface TokenResponse {
+	access_token: string;
+	token_type: string;
+	scope?: string;
+	expires_in?: number;
+	refresh_token?: string;
+	refresh_token_expires_in?: number;
+}
+
+/** RFC 6749 §5.2 / RFC 8628 §3.5 error response. */
+export class OAuthError extends Error {
+	override name = 'OAuthError';
+
+	constructor(
+		public readonly code: string,
+		public readonly status: number,
+		public readonly description?: string,
+	) {
+		super(description ? `${code}: ${description}` : code);
+	}
+}
+
+export type TokenRequestResult = { ok: true; tokens: TokenResponse } | { ok: false; error: OAuthError };
+
+/**
+ * POSTs a form-encoded request to the token endpoint. Network failures throw; OAuth error responses
+ * are returned so the caller can branch on `error.code` (`authorization_pending`, `slow_down`, ...).
+ */
+export async function postTokenRequest(
+	tokenEndpoint: string,
+	params: Record<string, string>,
+): Promise<TokenRequestResult> {
+	const response = await fetch(tokenEndpoint, {
+		method: 'POST',
+		headers: {
+			'Content-Type': 'application/x-www-form-urlencoded',
+			Accept: 'application/json',
+			...APIFY_CLIENT_DEFAULT_HEADERS,
+		},
+		body: new URLSearchParams(params),
+		signal: AbortSignal.timeout(OAUTH_REQUEST_TIMEOUT_MS),
+	});
+
+	const text = await response.text();
+	let body: Record<string, unknown> = {};
+	try {
+		body = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+	} catch {
+		// Non-JSON bodies are reported through the status code below.
+	}
+
+	if (response.ok && typeof body.access_token === 'string') {
+		return { ok: true, tokens: body as unknown as TokenResponse };
+	}
+
+	const code = typeof body.error === 'string' ? body.error : `http_${response.status}`;
+	const description = typeof body.error_description === 'string' ? body.error_description : undefined;
+	return { ok: false, error: new OAuthError(code, response.status, description) };
+}
+
+export async function refreshAccessToken(params: {
+	tokenEndpoint: string;
+	clientId: string;
+	refreshToken: string;
+}): Promise<TokenResponse> {
+	const result = await postTokenRequest(params.tokenEndpoint, {
+		grant_type: 'refresh_token',
+		refresh_token: params.refreshToken,
+		client_id: params.clientId,
+	});
+
+	if (!result.ok) throw result.error;
+	return result.tokens;
+}
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index 99d8784e8..80fcfbeda 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -41,10 +41,11 @@ import {
 	MINIMUM_SUPPORTED_PYTHON_VERSION,
 	SUPPORTED_NODEJS_VERSION,
 } from './consts.js';
-import { ensureMigrated, getBackend, getProxyPassword, getToken, setProxyPassword, setToken } from './credentials.js';
+import { ensureMigrated, getBackend, getProxyPassword, setProxyPassword, setToken } from './credentials.js';
 import { deleteFile, ensureApifyDirectory, ensureFolderExistsSync, rimrafPromised } from './files.js';
 import { useCLIMetadata } from './hooks/useCLIMetadata.js';
 import { inputFileRegExp, TEMP_INPUT_KEY_PREFIX } from './input-key.js';
+import { getAccessToken } from './oauth/session.js';
 import type { AuthJSON } from './types.js';
 import { cliDebugPrint } from './utils/cliDebugPrint.js';
 
@@ -98,14 +99,18 @@ export const getLocalUserInfo = async (): Promise<AuthJSON> => {
 		// auth.json may not exist yet (fresh keyring-only state); fall through
 	}
 
-	if ((await getBackend()) === 'keyring') {
-		const token = await getToken();
-		if (token) result.token = token;
+	// Refreshes an OAuth-issued token when it is about to expire; a plain API token passes through.
+	const token = await getAccessToken();
+	if (token) result.token = token;
 
+	if ((await getBackend()) === 'keyring') {
 		const proxyPassword = await getProxyPassword();
 		if (proxyPassword) result.proxy = { ...result.proxy, password: proxyPassword };
 	}
 
+	// OAuth session state is internal; callers that need it use `getOAuthMetadata()`.
+	delete (result as Record<string, unknown>).oauth;
+
 	const hasUserMetadata = !!(result.username || result.id);
 	const isComplete = hasUserMetadata || !!result.token;
 	if (!isComplete) return {};
@@ -132,7 +137,7 @@ export async function getLoggedClientOrThrow() {
 const resolveToken = async (existingToken?: string): Promise<string | undefined> => {
 	if (existingToken) return existingToken;
 	await ensureMigrated();
-	return getToken();
+	return getAccessToken();
 };
 
 type CJSAxiosHeaders = import('axios', { with: { 'resolution-mode': 'require' } }).AxiosRequestConfig['headers'];
@@ -208,6 +213,10 @@ export async function getLoggedClient(token?: string, apiBaseUrl?: string) {
 				delete fileContents.proxy;
 			}
 		}
+		if (fileContents.oauth && typeof fileContents.oauth === 'object') {
+			const { refreshToken: _refreshToken, ...rest } = fileContents.oauth as { refreshToken?: string };
+			fileContents.oauth = rest;
+		}
 	}
 	writeFileSync(AUTH_FILE_PATH(), JSON.stringify(fileContents, null, '\t'), { mode: 0o600 });
 
diff --git a/test/local/commands/auth-login.test.ts b/test/local/commands/auth-login.test.ts
new file mode 100644
index 000000000..0adacfb61
--- /dev/null
+++ b/test/local/commands/auth-login.test.ts
@@ -0,0 +1,285 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import open from 'open';
+
+import { AUTH_FILE_PATH } from '../../../src/lib/consts.js';
+import { useAuthSetup } from '../../__setup__/hooks/useAuthSetup.js';
+import { useConsoleSpy } from '../../__setup__/hooks/useConsoleSpy.js';
+
+vi.mock('open', () => ({ default: vi.fn(async () => undefined) }));
+vi.mock('computer-name', () => ({ default: () => 'test-machine' }));
+// Device-code polling and the refresh lock both sleep through this; the tests should not.
+vi.mock('node:timers/promises', async (importOriginal) => ({
+	...(await importOriginal<typeof import('node:timers/promises')>()),
+	setTimeout: vi.fn(async () => undefined),
+}));
+
+const fakeUser = { id: 'user-1', username: 'tester', email: 'tester@example.com' };
+
+vi.mock('apify-client', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('apify-client')>();
+	class ApifyClient {
+		token?: string;
+		constructor(options: { token?: string } = {}) {
+			this.token = options.token;
+		}
+		user() {
+			return {
+				get: async () => {
+					if (!this.token?.startsWith('valid_')) throw new Error('401 Unauthorized');
+					return { ...fakeUser };
+				},
+			};
+		}
+	}
+	return { ...actual, ApifyClient };
+});
+
+const keyringStore = new Map<string, string>();
+
+vi.mock('@napi-rs/keyring', () => {
+	class Entry {
+		private key: string;
+		constructor(service: string, account: string) {
+			this.key = `${service}:${account}`;
+		}
+		getPassword(): string | null {
+			return keyringStore.get(this.key) ?? null;
+		}
+		setPassword(password: string): void {
+			keyringStore.set(this.key, password);
+		}
+		deletePassword(): boolean {
+			return keyringStore.delete(this.key);
+		}
+	}
+	return { Entry };
+});
+
+useAuthSetup();
+
+const { logMessages } = useConsoleSpy();
+
+const { testRunCommand } = await import('../../../src/lib/command-framework/apify-command.js');
+const { LoginCommand } = await import('../../../src/commands/login.js');
+const { __resetCredentialsForTests } = await import('../../../src/lib/credentials.js');
+const { __resetOAuthSessionForTests, saveOAuthSession } = await import('../../../src/lib/oauth/session.js');
+const { getLoggedClient } = await import('../../../src/lib/utils.js');
+
+const ISSUER = 'https://issuer.test';
+const CLIENT_ID = 'https://client.test/oauth-client.json';
+
+const discovery = {
+	issuer: ISSUER,
+	authorization_endpoint: 'https://console.test/authorize/oauth',
+	device_authorization_endpoint: `${ISSUER}/oauth/apps/devices`,
+	token_endpoint: `${ISSUER}/oauth/apps/token`,
+	scopes_supported: ['full_api_access'],
+};
+
+const deviceResponse = {
+	device_code: 'dev-code',
+	user_code: 'ABCD-EFGH',
+	verification_uri: 'https://console.test/authorize/device',
+	verification_uri_complete: 'https://console.test/authorize/device?code=ABCD-EFGH',
+	expires_in: 300,
+	interval: 5,
+};
+
+const tokens = {
+	access_token: 'valid_integration_token',
+	token_type: 'Bearer',
+	scope: 'full_api_access',
+	expires_in: 3599,
+	refresh_token: 'rt-1',
+	refresh_token_expires_in: 5183999,
+};
+
+const realFetch = globalThis.fetch;
+const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+const readAuthFile = () => (existsSync(AUTH_FILE_PATH()) ? JSON.parse(readFileSync(AUTH_FILE_PATH(), 'utf-8')) : {});
+const allErrorOutput = () => logMessages.error.join('\n');
+
+interface FakeServer {
+	discovery?: () => Response | Promise<Response>;
+	device?: () => Response;
+	token: (() => Response)[];
+}
+
+/** Answers the OAuth endpoints from memory; anything else (the loopback redirect) goes over the wire. */
+const mockServer = ({ discovery: discoveryHandler = () => json(discovery), device, token }: FakeServer) => {
+	const tokenQueue = [...token];
+	return vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+		const url = String(input);
+		if (url === `${ISSUER}/.well-known/oauth-authorization-server`) return discoveryHandler();
+		if (url === discovery.device_authorization_endpoint) return (device ?? (() => json(deviceResponse, 201)))();
+		if (url === discovery.token_endpoint) return tokenQueue.shift()!();
+		return realFetch(input, init);
+	});
+};
+
+const lastOpenedUrl = () => new URL(vi.mocked(open).mock.calls.at(-1)![0] as string);
+
+describe('apify login', () => {
+	beforeEach(() => {
+		vitest.stubEnv('APIFY_CLI_OAUTH_ISSUER_URL', ISSUER);
+		vitest.stubEnv('APIFY_CLI_OAUTH_CLIENT_ID', CLIENT_ID);
+		keyringStore.clear();
+		vi.mocked(open).mockClear();
+		__resetOAuthSessionForTests();
+	});
+
+	afterEach(() => {
+		__resetOAuthSessionForTests();
+		process.exitCode = undefined;
+	});
+
+	it('defaults to the device code flow and stores a refreshable session', async () => {
+		mockServer({ token: [() => json({ error: 'authorization_pending' }, 400), () => json(tokens)] });
+
+		await testRunCommand(LoginCommand, {});
+
+		expect(lastOpenedUrl().href).toBe(deviceResponse.verification_uri_complete);
+		expect(allErrorOutput()).toContain('ABCD-EFGH');
+		expect(allErrorOutput()).toContain('You are logged in to Apify as tester');
+
+		const file = readAuthFile();
+		expect(file.token).toBe('valid_integration_token');
+		expect(file.username).toBe('tester');
+		expect(file.oauth).toMatchObject({
+			issuer: ISSUER,
+			clientId: CLIENT_ID,
+			tokenEndpoint: discovery.token_endpoint,
+			refreshToken: 'rt-1',
+		});
+		expect(file.oauth.expiresAt).toBeGreaterThan(Date.now());
+	});
+
+	it('reports a denied device authorization and stops', async () => {
+		mockServer({ token: [() => json({ error: 'access_denied' }, 400)] });
+
+		await testRunCommand(LoginCommand, {});
+
+		expect(allErrorOutput()).toContain('denied in Apify Console');
+		expect(process.exitCode).toBe(1);
+		expect(readAuthFile().oauth).toBeUndefined();
+	});
+
+	it('cancels the login on an interrupt signal while waiting for the browser', async () => {
+		mockServer({ token: [] });
+		// Never authorized: every poll stays pending until the signal arrives.
+		vi.mocked(globalThis.fetch).mockImplementation(async (input, init) => {
+			const url = String(input);
+			if (url === `${ISSUER}/.well-known/oauth-authorization-server`) return json(discovery);
+			if (url === discovery.device_authorization_endpoint) return json(deviceResponse, 201);
+			if (url === discovery.token_endpoint) {
+				// The sleep between polls is mocked away in this file; yield a real tick so the signal can land.
+				await new Promise((resolve) => {
+					setTimeout(resolve, 10);
+				});
+				return json({ error: 'authorization_pending' }, 400);
+			}
+			return realFetch(input, init);
+		});
+
+		const run = testRunCommand(LoginCommand, {});
+		await vi.waitFor(() => expect(open).toHaveBeenCalled());
+
+		process.emit('SIGINT', 'SIGINT');
+		await run;
+
+		expect(allErrorOutput()).toContain('Login cancelled.');
+		expect(process.exitCode).toBe(1);
+		expect(readAuthFile().oauth).toBeUndefined();
+		expect(process.listenerCount('SIGINT')).toBe(0);
+	});
+
+	it('drops the session again when the API rejects the issued token', async () => {
+		mockServer({ token: [() => json({ ...tokens, access_token: 'bogus_token' })] });
+
+		await testRunCommand(LoginCommand, {});
+
+		expect(allErrorOutput()).toContain('was not accepted by the Apify API');
+		expect(readAuthFile().oauth).toBeUndefined();
+	});
+
+	it('falls back to the authorization code flow when device authorization is unavailable', async () => {
+		mockServer({ device: () => json({ error: 'not_found' }, 404), token: [() => json(tokens)] });
+
+		const run = testRunCommand(LoginCommand, {});
+		await vi.waitFor(() => expect(open).toHaveBeenCalled());
+
+		const authorizeUrl = lastOpenedUrl();
+		expect(authorizeUrl.origin + authorizeUrl.pathname).toBe(discovery.authorization_endpoint);
+
+		const redirect = new URL(authorizeUrl.searchParams.get('redirect_uri')!);
+		redirect.searchParams.set('code', 'auth-code');
+		redirect.searchParams.set('state', authorizeUrl.searchParams.get('state')!);
+		await realFetch(redirect);
+
+		await run;
+
+		expect(allErrorOutput()).toContain('You are logged in to Apify as tester');
+		expect(readAuthFile().oauth).toMatchObject({ refreshToken: 'rt-1' });
+	});
+
+	it('falls back to the legacy Console hand-off when discovery fails', async () => {
+		mockServer({ discovery: () => Promise.reject(new Error('ECONNREFUSED')), token: [] });
+
+		await testRunCommand(LoginCommand, {});
+
+		expect(allErrorOutput()).toContain('Using the Console login instead');
+
+		const consoleUrl = lastOpenedUrl();
+		expect(consoleUrl.searchParams.get('localCliCommand')).toBe('login');
+		const port = consoleUrl.searchParams.get('localCliPort')!;
+		const token = consoleUrl.searchParams.get('localCliToken')!;
+
+		// Shut the loopback server down the way Console would.
+		const response = await realFetch(`http://127.0.0.1:${port}/api/v1/exit`, {
+			method: 'POST',
+			headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+			body: JSON.stringify({ actionCanceled: true }),
+		});
+		expect(response.ok).toBe(true);
+	});
+
+	it('--token replaces an OAuth session with a plain token', async () => {
+		await saveOAuthSession(tokens, { issuer: ISSUER, clientId: CLIENT_ID, tokenEndpoint: discovery.token_endpoint });
+		expect(readAuthFile().oauth).toBeDefined();
+
+		await testRunCommand(LoginCommand, { flags_token: 'valid_plain_token' });
+
+		expect(allErrorOutput()).toContain('You are logged in to Apify as tester');
+		const file = readAuthFile();
+		expect(file.token).toBe('valid_plain_token');
+		expect(file.oauth).toBeUndefined();
+	});
+
+	it('keeps the refresh token out of auth.json on the keyring backend', async () => {
+		vitest.stubEnv('APIFY_DISABLE_KEYRING', '');
+		__resetCredentialsForTests();
+		mkdirSync(dirname(AUTH_FILE_PATH()), { recursive: true });
+		writeFileSync(
+			AUTH_FILE_PATH(),
+			JSON.stringify({
+				secretsBackend: 'keyring',
+				oauth: {
+					issuer: ISSUER,
+					clientId: CLIENT_ID,
+					tokenEndpoint: discovery.token_endpoint,
+					expiresAt: 1,
+					refreshToken: 'inline',
+				},
+			}),
+		);
+
+		await getLoggedClient('valid_token');
+
+		const file = readAuthFile();
+		expect(file.oauth).toMatchObject({ issuer: ISSUER });
+		expect(file.oauth.refreshToken).toBeUndefined();
+		expect(file.token).toBeUndefined();
+	});
+});
diff --git a/test/local/lib/credentials.test.ts b/test/local/lib/credentials.test.ts
index 4a0566ed8..3fa4be192 100644
--- a/test/local/lib/credentials.test.ts
+++ b/test/local/lib/credentials.test.ts
@@ -7,10 +7,15 @@ import { AUTH_FILE_PATH, GLOBAL_CONFIGS_FOLDER } from '../../../src/lib/consts.j
 import {
 	__resetCredentialsForTests,
 	clearKeyringSecrets,
+	clearOAuthState,
 	ensureMigrated,
 	getBackend,
+	getOAuthMetadata,
+	getOAuthRefreshToken,
 	getProxyPassword,
 	getToken,
+	setOAuthMetadata,
+	setOAuthRefreshToken,
 	setProxyPassword,
 	setToken,
 } from '../../../src/lib/credentials.js';
@@ -254,6 +259,77 @@ describe('credentials', () => {
 		});
 	});
 
+	describe('oauth state', () => {
+		const metadata = {
+			issuer: 'https://issuer.test',
+			clientId: 'https://client.test/oauth-client.json',
+			tokenEndpoint: 'https://issuer.test/oauth/apps/token',
+			expiresAt: 1_700_000_000_000,
+			refreshTokenExpiresAt: 1_800_000_000_000,
+		};
+
+		it('on file backend, keeps the refresh token inline next to the metadata', async () => {
+			vitest.stubEnv('APIFY_DISABLE_KEYRING', '1');
+			await setOAuthRefreshToken('rt_1');
+			setOAuthMetadata(metadata);
+
+			expect(await getOAuthRefreshToken()).toBe('rt_1');
+			expect(getOAuthMetadata()).toEqual(metadata);
+			expect(readAuthFile().oauth).toEqual({ ...metadata, refreshToken: 'rt_1' });
+		});
+
+		it('on keyring backend, keeps the refresh token out of auth.json', async () => {
+			vitest.stubEnv('APIFY_DISABLE_KEYRING', '');
+			await setOAuthRefreshToken('rt_1');
+			setOAuthMetadata(metadata);
+
+			expect(keyringStore.get('com.apify.cli:oauth-refresh-token')).toBe('rt_1');
+			expect(await getOAuthRefreshToken()).toBe('rt_1');
+			expect(readAuthFile().oauth).toEqual(metadata);
+		});
+
+		it('falls back to the file when the keyring write fails', async () => {
+			vitest.stubEnv('APIFY_DISABLE_KEYRING', '');
+			keyringFailures.add('com.apify.cli:oauth-refresh-token');
+			await setOAuthRefreshToken('rt_1');
+
+			expect(await getOAuthRefreshToken()).toBe('rt_1');
+			expect(readAuthFile().oauth).toEqual({ refreshToken: 'rt_1' });
+			expect(readAuthFile().secretsBackend).toBe('file');
+		});
+
+		it('getOAuthMetadata() ignores an incomplete record', async () => {
+			vitest.stubEnv('APIFY_DISABLE_KEYRING', '1');
+			writeAuthFile({ oauth: { refreshToken: 'rt_1' } } as never);
+
+			expect(getOAuthMetadata()).toBeUndefined();
+		});
+
+		it('clearOAuthState() removes the refresh token and metadata but keeps the access token', async () => {
+			vitest.stubEnv('APIFY_DISABLE_KEYRING', '1');
+			await setToken('tok');
+			await setOAuthRefreshToken('rt_1');
+			setOAuthMetadata(metadata);
+
+			await clearOAuthState();
+
+			expect(await getToken()).toBe('tok');
+			expect(await getOAuthRefreshToken()).toBeUndefined();
+			expect(getOAuthMetadata()).toBeUndefined();
+			expect(readAuthFile().oauth).toBeUndefined();
+		});
+
+		it('clearKeyringSecrets() removes the refresh token entry', async () => {
+			vitest.stubEnv('APIFY_DISABLE_KEYRING', '');
+			await setOAuthRefreshToken('rt_1');
+			expect(keyringStore.has('com.apify.cli:oauth-refresh-token')).toBe(true);
+
+			await clearKeyringSecrets();
+
+			expect(keyringStore.has('com.apify.cli:oauth-refresh-token')).toBe(false);
+		});
+	});
+
 	describe('getLocalUserInfo()', () => {
 		it('on file backend, preserves non-secret proxy fields', async () => {
 			vitest.stubEnv('APIFY_DISABLE_KEYRING', '1');
diff --git a/test/local/lib/oauth/authorization-code.test.ts b/test/local/lib/oauth/authorization-code.test.ts
new file mode 100644
index 000000000..84902eb3a
--- /dev/null
+++ b/test/local/lib/oauth/authorization-code.test.ts
@@ -0,0 +1,145 @@
+import { loginWithAuthorizationCode, pkceChallengeFromVerifier } from '../../../../src/lib/oauth/authorization-code.js';
+import type { AuthorizationServerMetadata } from '../../../../src/lib/oauth/discovery.js';
+
+const ISSUER = 'https://issuer.test';
+const CLIENT_ID = 'https://client.test/oauth-client.json';
+
+const metadata: AuthorizationServerMetadata = {
+	issuer: ISSUER,
+	authorization_endpoint: 'https://console.test/authorize/oauth',
+	token_endpoint: `${ISSUER}/oauth/apps/token`,
+};
+
+const tokens = {
+	access_token: 'integration_api_token_new',
+	token_type: 'Bearer',
+	expires_in: 3599,
+	refresh_token: 'rt-1',
+};
+
+const realFetch = globalThis.fetch;
+const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+
+/** Mocks only the token endpoint; everything else (the loopback redirect) goes over the wire. */
+const mockTokenEndpoint = (respond: () => Response) =>
+	vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+		if (String(input) === metadata.token_endpoint) return respond();
+		return realFetch(input, init);
+	});
+
+/** Starts the flow and hands back the authorize URL the user would be sent to. */
+const start = async (respondToExchange: () => Response = () => json(tokens)) => {
+	const fetchSpy = mockTokenEndpoint(respondToExchange);
+	let authorizeUrl!: URL;
+	const finished = loginWithAuthorizationCode({
+		metadata,
+		clientId: CLIENT_ID,
+		onPrompt: (url) => {
+			authorizeUrl = new URL(url);
+		},
+	});
+	await vi.waitFor(() => expect(authorizeUrl).toBeDefined());
+
+	const redirect = (params: Record<string, string>) => {
+		const url = new URL(authorizeUrl.searchParams.get('redirect_uri')!);
+		for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+		return realFetch(url);
+	};
+
+	return { finished, authorizeUrl, redirect, fetchSpy };
+};
+
+describe('pkceChallengeFromVerifier', () => {
+	// RFC 7636 Appendix B.
+	it('derives the S256 challenge', () => {
+		expect(pkceChallengeFromVerifier('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk')).toBe(
+			'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
+		);
+	});
+});
+
+describe('loginWithAuthorizationCode', () => {
+	it('is unsupported when the server has no authorization endpoint', async () => {
+		const onPrompt = vi.fn();
+		const result = await loginWithAuthorizationCode({
+			metadata: { issuer: ISSUER, token_endpoint: metadata.token_endpoint },
+			clientId: CLIENT_ID,
+			onPrompt,
+		});
+
+		expect(result).toMatchObject({ unsupported: true });
+		expect(onPrompt).not.toHaveBeenCalled();
+	});
+
+	it('builds a PKCE authorize URL with a loopback redirect and exchanges the code', async () => {
+		const { finished, authorizeUrl, redirect, fetchSpy } = await start();
+
+		expect(authorizeUrl.origin + authorizeUrl.pathname).toBe(metadata.authorization_endpoint);
+		expect(authorizeUrl.searchParams.get('response_type')).toBe('code');
+		expect(authorizeUrl.searchParams.get('client_id')).toBe(CLIENT_ID);
+		expect(authorizeUrl.searchParams.get('scope')).toBe('full_api_access');
+		expect(authorizeUrl.searchParams.get('code_challenge_method')).toBe('S256');
+		expect(authorizeUrl.searchParams.get('redirect_uri')).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/callback$/);
+
+		const state = authorizeUrl.searchParams.get('state')!;
+		const response = await redirect({ code: 'auth-code', state });
+		expect(response.status).toBe(200);
+		expect(await response.text()).toContain('You can close this tab');
+
+		expect(await finished).toEqual({ tokens });
+
+		const exchange = fetchSpy.mock.calls.find(([input]) => String(input) === metadata.token_endpoint)!;
+		const body = Object.fromEntries(exchange[1]!.body as URLSearchParams);
+		expect(body).toMatchObject({
+			grant_type: 'authorization_code',
+			code: 'auth-code',
+			redirect_uri: authorizeUrl.searchParams.get('redirect_uri'),
+			client_id: CLIENT_ID,
+		});
+		expect(pkceChallengeFromVerifier(body.code_verifier)).toBe(authorizeUrl.searchParams.get('code_challenge'));
+	});
+
+	it('ignores a redirect with the wrong state and keeps waiting', async () => {
+		const { finished, authorizeUrl, redirect } = await start();
+
+		const bogus = await redirect({ code: 'evil', state: 'not-ours' });
+		expect(bogus.status).toBe(400);
+
+		await redirect({ code: 'auth-code', state: authorizeUrl.searchParams.get('state')! });
+		expect(await finished).toEqual({ tokens });
+	});
+
+	it('stops when the authorization server reports an error', async () => {
+		const { finished, authorizeUrl, redirect } = await start();
+
+		await redirect({
+			error: 'access_denied',
+			error_description: 'User denied',
+			state: authorizeUrl.searchParams.get('state')!,
+		});
+
+		expect(await finished).toMatchObject({
+			stopReason: 'accessDenied',
+			message: expect.stringContaining('User denied'),
+		});
+	});
+
+	it('reports a failed code exchange', async () => {
+		const { finished, authorizeUrl, redirect } = await start(() => json({ error: 'invalid_grant' }, 400));
+
+		await redirect({ code: 'auth-code', state: authorizeUrl.searchParams.get('state')! });
+
+		expect(await finished).toMatchObject({ stopReason: 'exchangeFailed' });
+	});
+
+	it('times out when the browser never comes back', async () => {
+		vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+		try {
+			const { finished } = await start();
+			await vi.advanceTimersByTimeAsync(5 * 60_000);
+			expect(await finished).toMatchObject({ stopReason: 'timedOut' });
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+});
diff --git a/test/local/lib/oauth/device-code.test.ts b/test/local/lib/oauth/device-code.test.ts
new file mode 100644
index 000000000..3885a7c26
--- /dev/null
+++ b/test/local/lib/oauth/device-code.test.ts
@@ -0,0 +1,181 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import { loginWithDeviceCode } from '../../../../src/lib/oauth/device-code.js';
+import type { AuthorizationServerMetadata } from '../../../../src/lib/oauth/discovery.js';
+
+vi.mock('node:timers/promises', async (importOriginal) => ({
+	...(await importOriginal<typeof import('node:timers/promises')>()),
+	setTimeout: vi.fn(async (_ms: number, _value: unknown, opts?: { signal?: AbortSignal }) => {
+		if (opts?.signal?.aborted) throw new Error('The operation was aborted');
+	}),
+}));
+
+const ISSUER = 'https://issuer.test';
+const CLIENT_ID = 'https://client.test/oauth-client.json';
+
+const metadata: AuthorizationServerMetadata = {
+	issuer: ISSUER,
+	device_authorization_endpoint: `${ISSUER}/oauth/apps/devices`,
+	token_endpoint: `${ISSUER}/oauth/apps/token`,
+};
+
+const deviceResponse = {
+	device_code: 'dev-code',
+	user_code: 'ABCD-EFGH',
+	verification_uri: 'https://console.test/authorize/device',
+	verification_uri_complete: 'https://console.test/authorize/device?code=ABCD-EFGH',
+	expires_in: 300,
+	interval: 5,
+};
+
+const tokens = {
+	access_token: 'integration_api_token_new',
+	token_type: 'Bearer',
+	scope: 'full_api_access',
+	expires_in: 3599,
+	refresh_token: 'rt-1',
+	refresh_token_expires_in: 5183999,
+};
+
+const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+const oauthError = (error: string) => json({ error }, 400);
+
+/** Routes the device endpoint to `device` and hands out `tokenResponses` in order for the token endpoint. */
+const mockServer = (device: () => Response, tokenResponses: (() => Response)[]) => {
+	const queue = [...tokenResponses];
+	return vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+		const url = String(input);
+		if (url === metadata.device_authorization_endpoint) return device();
+		if (url === metadata.token_endpoint) return queue.shift()!();
+		throw new Error(`unexpected fetch ${url}`);
+	});
+};
+
+const sleepDurations = () => vi.mocked(sleep).mock.calls.map(([ms]) => ms);
+
+const formBody = (call: [RequestInfo | URL, RequestInit?]) => Object.fromEntries(call[1]!.body as URLSearchParams);
+
+describe('loginWithDeviceCode', () => {
+	beforeEach(() => {
+		vi.mocked(sleep).mockClear();
+	});
+
+	it('is unsupported when the server has no device authorization endpoint', async () => {
+		const onPrompt = vi.fn();
+		const result = await loginWithDeviceCode({
+			metadata: { issuer: ISSUER, token_endpoint: metadata.token_endpoint },
+			clientId: CLIENT_ID,
+			onPrompt,
+		});
+
+		expect(result).toMatchObject({ unsupported: true });
+		expect(onPrompt).not.toHaveBeenCalled();
+	});
+
+	it('is unsupported when the device authorization request fails before the user is involved', async () => {
+		mockServer(() => json({ error: 'not_found' }, 404), []);
+		const onPrompt = vi.fn();
+
+		const result = await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt });
+
+		expect(result).toMatchObject({ unsupported: true });
+		expect(onPrompt).not.toHaveBeenCalled();
+	});
+
+	it('prompts, polls at the server interval, and returns the tokens', async () => {
+		const fetchSpy = mockServer(
+			() => json(deviceResponse, 201),
+			[() => oauthError('authorization_pending'), () => json(tokens)],
+		);
+		const onPrompt = vi.fn();
+
+		const result = await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt });
+
+		expect(result).toEqual({ tokens });
+		expect(onPrompt).toHaveBeenCalledWith({
+			verificationUri: deviceResponse.verification_uri,
+			verificationUriComplete: deviceResponse.verification_uri_complete,
+			userCode: deviceResponse.user_code,
+			expiresInSeconds: 300,
+		});
+
+		expect(formBody(fetchSpy.mock.calls[0] as never)).toEqual({ client_id: CLIENT_ID, scope: 'full_api_access' });
+		expect(formBody(fetchSpy.mock.calls[1] as never)).toEqual({
+			grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+			device_code: 'dev-code',
+			client_id: CLIENT_ID,
+		});
+		expect(sleepDurations()).toEqual([5000, 5000]);
+	});
+
+	it('honours a non-default interval from the server', async () => {
+		mockServer(() => json({ ...deviceResponse, interval: 7 }, 201), [() => json(tokens)]);
+
+		await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt: vi.fn() });
+
+		expect(sleepDurations()).toEqual([7000]);
+	});
+
+	it('falls back to a 5 second interval when the server omits it', async () => {
+		const { interval: _omitted, ...withoutInterval } = deviceResponse;
+		mockServer(() => json(withoutInterval, 201), [() => json(tokens)]);
+
+		await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt: vi.fn() });
+
+		expect(sleepDurations()).toEqual([5000]);
+	});
+
+	it('adds 5 seconds to the interval on slow_down', async () => {
+		mockServer(
+			() => json(deviceResponse, 201),
+			[() => oauthError('slow_down'), () => oauthError('authorization_pending'), () => json(tokens)],
+		);
+
+		await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt: vi.fn() });
+
+		expect(sleepDurations()).toEqual([5000, 10_000, 10_000]);
+	});
+
+	it('stops when the user denies the request', async () => {
+		mockServer(() => json(deviceResponse, 201), [() => oauthError('access_denied')]);
+
+		const result = await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt: vi.fn() });
+
+		expect(result).toMatchObject({ stopReason: 'accessDenied' });
+	});
+
+	it('stops when the device code expires', async () => {
+		mockServer(() => json(deviceResponse, 201), [() => oauthError('expired_token')]);
+
+		const result = await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt: vi.fn() });
+
+		expect(result).toMatchObject({ stopReason: 'expired' });
+	});
+
+	it('keeps polling through a transient network error', async () => {
+		const queue = [() => Promise.reject(new Error('ECONNRESET')), async () => json(tokens)];
+		vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+			if (String(input) === metadata.device_authorization_endpoint) return json(deviceResponse, 201);
+			return queue.shift()!();
+		});
+
+		const result = await loginWithDeviceCode({ metadata, clientId: CLIENT_ID, onPrompt: vi.fn() });
+
+		expect(result).toEqual({ tokens });
+	});
+
+	it('stops when aborted', async () => {
+		mockServer(() => json(deviceResponse, 201), []);
+		const controller = new AbortController();
+		controller.abort();
+
+		const result = await loginWithDeviceCode({
+			metadata,
+			clientId: CLIENT_ID,
+			signal: controller.signal,
+			onPrompt: vi.fn(),
+		});
+
+		expect(result).toMatchObject({ stopReason: 'aborted' });
+	});
+});
diff --git a/test/local/lib/oauth/discovery.test.ts b/test/local/lib/oauth/discovery.test.ts
new file mode 100644
index 000000000..507321c87
--- /dev/null
+++ b/test/local/lib/oauth/discovery.test.ts
@@ -0,0 +1,56 @@
+import { fetchAuthorizationServerMetadata, OAuthDiscoveryError } from '../../../../src/lib/oauth/discovery.js';
+
+const ISSUER = 'https://issuer.test';
+
+const validDocument = {
+	issuer: ISSUER,
+	authorization_endpoint: 'https://console.test/authorize/oauth',
+	device_authorization_endpoint: `${ISSUER}/oauth/apps/devices`,
+	token_endpoint: `${ISSUER}/oauth/apps/token`,
+	scopes_supported: ['full_api_access'],
+};
+
+const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+
+describe('fetchAuthorizationServerMetadata', () => {
+	it('fetches the RFC 8414 document under the issuer', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(json(validDocument));
+
+		const metadata = await fetchAuthorizationServerMetadata(ISSUER);
+
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+		expect(fetchSpy.mock.calls[0][0]).toBe(`${ISSUER}/.well-known/oauth-authorization-server`);
+		expect(metadata).toEqual(validDocument);
+	});
+
+	it('rejects a non-2xx response', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(json({ error: 'nope' }, 404));
+
+		await expect(fetchAuthorizationServerMetadata(ISSUER)).rejects.toBeInstanceOf(OAuthDiscoveryError);
+	});
+
+	it('rejects a network failure', async () => {
+		vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('ECONNREFUSED'));
+
+		await expect(fetchAuthorizationServerMetadata(ISSUER)).rejects.toThrow(/Could not reach/);
+	});
+
+	it('rejects a document whose issuer does not match', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(json({ ...validDocument, issuer: 'https://other.test' }));
+
+		await expect(fetchAuthorizationServerMetadata(ISSUER)).rejects.toThrow(/reports issuer/);
+	});
+
+	it('rejects a document without a token endpoint', async () => {
+		const { token_endpoint: _omitted, ...withoutTokenEndpoint } = validDocument;
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(json(withoutTokenEndpoint));
+
+		await expect(fetchAuthorizationServerMetadata(ISSUER)).rejects.toThrow(/token_endpoint/);
+	});
+
+	it('rejects a body that is not JSON', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('<html>', { status: 200 }));
+
+		await expect(fetchAuthorizationServerMetadata(ISSUER)).rejects.toThrow(/valid JSON/);
+	});
+});
diff --git a/test/local/lib/oauth/session.test.ts b/test/local/lib/oauth/session.test.ts
new file mode 100644
index 000000000..1ef82cef3
--- /dev/null
+++ b/test/local/lib/oauth/session.test.ts
@@ -0,0 +1,300 @@
+import { existsSync, mkdirSync, readFileSync, utimesSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { cryptoRandomObjectId } from '@apify/utilities';
+
+import { AUTH_FILE_PATH, GLOBAL_CONFIGS_FOLDER } from '../../../../src/lib/consts.js';
+import {
+	__resetCredentialsForTests,
+	getOAuthMetadata,
+	getOAuthRefreshToken,
+	getToken,
+	setOAuthMetadata,
+	setOAuthRefreshToken,
+	setToken,
+} from '../../../../src/lib/credentials.js';
+import {
+	__resetOAuthSessionForTests,
+	clearOAuthSession,
+	getAccessToken,
+	OAuthSessionExpiredError,
+	saveOAuthSession,
+} from '../../../../src/lib/oauth/session.js';
+import { getLocalUserInfo } from '../../../../src/lib/utils.js';
+
+const keyringStore = new Map<string, string>();
+
+vi.mock('@napi-rs/keyring', () => {
+	class Entry {
+		private key: string;
+		constructor(service: string, account: string) {
+			this.key = `${service}:${account}`;
+		}
+		getPassword(): string | null {
+			return keyringStore.get(this.key) ?? null;
+		}
+		setPassword(password: string): void {
+			keyringStore.set(this.key, password);
+		}
+		deletePassword(): boolean {
+			return keyringStore.delete(this.key);
+		}
+	}
+	return { Entry };
+});
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const ISSUER = 'https://issuer.test';
+const CLIENT_ID = 'https://client.test/oauth-client.json';
+const TOKEN_ENDPOINT = `${ISSUER}/oauth/apps/token`;
+
+const readAuthFile = () => JSON.parse(readFileSync(AUTH_FILE_PATH(), 'utf-8'));
+const lockPath = () => join(GLOBAL_CONFIGS_FOLDER(), 'oauth-refresh.lock');
+
+const seedSession = async ({
+	token = 'tok_old',
+	refreshToken = 'rt_1',
+	expiresInMs = HOUR,
+	refreshTokenExpiresInMs = 60 * DAY,
+}: { token?: string; refreshToken?: string; expiresInMs?: number; refreshTokenExpiresInMs?: number } = {}) => {
+	await setToken(token);
+	await setOAuthRefreshToken(refreshToken);
+	setOAuthMetadata({
+		issuer: ISSUER,
+		clientId: CLIENT_ID,
+		tokenEndpoint: TOKEN_ENDPOINT,
+		expiresAt: Date.now() + expiresInMs,
+		refreshTokenExpiresAt: Date.now() + refreshTokenExpiresInMs,
+	});
+};
+
+const tokenResponse = (overrides: Record<string, unknown> = {}) =>
+	new Response(
+		JSON.stringify({
+			access_token: 'tok_new',
+			token_type: 'Bearer',
+			scope: 'full_api_access',
+			expires_in: 3599,
+			refresh_token: 'rt_2',
+			refresh_token_expires_in: 5183999,
+			...overrides,
+		}),
+		{ status: 200 },
+	);
+
+const oauthError = (error: string) => new Response(JSON.stringify({ error }), { status: 400 });
+
+const formBody = (init: RequestInit | undefined) => Object.fromEntries(init!.body as URLSearchParams);
+
+describe.each([
+	['file', '1'],
+	['keyring', ''],
+])('oauth session on the %s backend', (_backend, disableKeyring) => {
+	beforeEach(() => {
+		vitest.stubEnv('__APIFY_INTERNAL_TEST_AUTH_PATH__', cryptoRandomObjectId(12));
+		vitest.stubEnv('APIFY_DISABLE_KEYRING', disableKeyring);
+		keyringStore.clear();
+		__resetCredentialsForTests();
+		__resetOAuthSessionForTests();
+	});
+
+	afterEach(async () => {
+		await rm(GLOBAL_CONFIGS_FOLDER(), { recursive: true, force: true });
+		vitest.unstubAllEnvs();
+		__resetCredentialsForTests();
+		__resetOAuthSessionForTests();
+		process.exitCode = undefined;
+	});
+
+	it('passes a plain API token through without touching the network', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch');
+		await setToken('apify_api_plain');
+
+		expect(await getAccessToken()).toBe('apify_api_plain');
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+
+	it('returns the stored token while it is fresh', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch');
+		await seedSession({ expiresInMs: 30 * MINUTE });
+
+		expect(await getAccessToken()).toBe('tok_old');
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+
+	it('refreshes an expiring token and stores the rotated pair', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse());
+		await seedSession({ expiresInMs: 30_000 });
+		const before = Date.now();
+
+		expect(await getAccessToken()).toBe('tok_new');
+
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+		expect(fetchSpy.mock.calls[0][0]).toBe(TOKEN_ENDPOINT);
+		expect(formBody(fetchSpy.mock.calls[0][1])).toEqual({
+			grant_type: 'refresh_token',
+			refresh_token: 'rt_1',
+			client_id: CLIENT_ID,
+		});
+
+		expect(await getToken()).toBe('tok_new');
+		expect(await getOAuthRefreshToken()).toBe('rt_2');
+		const metadata = getOAuthMetadata()!;
+		expect(metadata.expiresAt).toBeGreaterThanOrEqual(before + 3599_000);
+		expect(metadata.refreshTokenExpiresAt).toBeGreaterThanOrEqual(before + 5183999_000);
+		expect(existsSync(lockPath())).toBe(false);
+	});
+
+	it('refreshes when the refresh token itself is about to expire, even with a fresh access token', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse());
+		await seedSession({ expiresInMs: 50 * MINUTE, refreshTokenExpiresInMs: 20 * MINUTE });
+
+		expect(await getAccessToken()).toBe('tok_new');
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+		expect(getOAuthMetadata()!.refreshTokenExpiresAt).toBeGreaterThan(Date.now() + DAY);
+	});
+
+	it('keeps the previous refresh token when the server does not rotate it', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse({ refresh_token: undefined }));
+		await seedSession({ expiresInMs: 30_000 });
+
+		await getAccessToken();
+
+		expect(await getOAuthRefreshToken()).toBe('rt_1');
+	});
+
+	it('refreshes at most once per process', async () => {
+		// The new token is itself nearly expired, so a second call would want to refresh again.
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse({ expires_in: 10 }));
+		await seedSession({ expiresInMs: 30_000 });
+
+		expect(await getAccessToken()).toBe('tok_new');
+		expect(await getAccessToken()).toBe('tok_new');
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('shares one refresh between concurrent callers', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse());
+		await seedSession({ expiresInMs: 30_000 });
+
+		const results = await Promise.all([getAccessToken(), getAccessToken(), getAccessToken()]);
+
+		expect(results).toEqual(['tok_new', 'tok_new', 'tok_new']);
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('honours a larger minRemainingMs', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse());
+		await seedSession({ expiresInMs: 20 * MINUTE });
+
+		expect(await getAccessToken()).toBe('tok_old');
+		expect(fetchSpy).not.toHaveBeenCalled();
+
+		expect(await getAccessToken({ minRemainingMs: 45 * MINUTE })).toBe('tok_new');
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('reports an expired session without a network call when the refresh token is gone', async () => {
+		const fetchSpy = vi.spyOn(globalThis, 'fetch');
+		await seedSession({ expiresInMs: -1000, refreshTokenExpiresInMs: -1000 });
+
+		await expect(getAccessToken()).rejects.toBeInstanceOf(OAuthSessionExpiredError);
+		expect(fetchSpy).not.toHaveBeenCalled();
+		expect(process.exitCode).toBe(1);
+	});
+
+	it('clears the session when the server rejects the refresh token after hard expiry', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(oauthError('invalid_grant'));
+		await seedSession({ expiresInMs: -1000 });
+
+		await expect(getAccessToken()).rejects.toBeInstanceOf(OAuthSessionExpiredError);
+
+		expect(getOAuthMetadata()).toBeUndefined();
+		expect(await getOAuthRefreshToken()).toBeUndefined();
+		expect(await getToken()).toBe('tok_old');
+	});
+
+	it('falls back to the still-valid stored token when an early refresh is rejected', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(oauthError('invalid_grant'));
+		await seedSession({ expiresInMs: 30_000 });
+
+		expect(await getAccessToken()).toBe('tok_old');
+		expect(getOAuthMetadata()).toBeDefined();
+	});
+
+	it('adopts the tokens written by a concurrent process that won the refresh race', async () => {
+		await seedSession({ expiresInMs: 30_000 });
+		const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
+			// The other process rotated everything while our request was in flight.
+			await setOAuthRefreshToken('rt_other');
+			await setToken('tok_other');
+			setOAuthMetadata({ ...getOAuthMetadata()!, expiresAt: Date.now() + HOUR });
+			return oauthError('invalid_grant');
+		});
+
+		expect(await getAccessToken()).toBe('tok_other');
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+		expect(await getOAuthRefreshToken()).toBe('rt_other');
+	});
+
+	it('survives a network error while the stored token is still valid', async () => {
+		vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('ECONNRESET'));
+		await seedSession({ expiresInMs: 30_000 });
+
+		expect(await getAccessToken()).toBe('tok_old');
+	});
+
+	it('fails with a network message once the stored token is past expiry', async () => {
+		vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('ECONNRESET'));
+		await seedSession({ expiresInMs: -1000 });
+
+		await expect(getAccessToken()).rejects.toThrow(/Could not refresh your Apify session/);
+		expect(getOAuthMetadata()).toBeDefined();
+	});
+
+	it('removes a stale refresh lock and proceeds', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse());
+		await seedSession({ expiresInMs: 30_000 });
+		mkdirSync(GLOBAL_CONFIGS_FOLDER(), { recursive: true });
+		writeFileSync(lockPath(), '12345');
+		const minuteAgo = (Date.now() - MINUTE) / 1000;
+		utimesSync(lockPath(), minuteAgo, minuteAgo);
+
+		expect(await getAccessToken()).toBe('tok_new');
+		expect(existsSync(lockPath())).toBe(false);
+	});
+
+	it('saveOAuthSession stores the tokens and clearOAuthSession forgets them', async () => {
+		await saveOAuthSession(
+			{ access_token: 'tok_login', token_type: 'Bearer', expires_in: 3599, refresh_token: 'rt_login' },
+			{ issuer: ISSUER, clientId: CLIENT_ID, tokenEndpoint: TOKEN_ENDPOINT },
+		);
+
+		expect(await getToken()).toBe('tok_login');
+		expect(await getOAuthRefreshToken()).toBe('rt_login');
+		expect(getOAuthMetadata()).toMatchObject({ issuer: ISSUER, clientId: CLIENT_ID, tokenEndpoint: TOKEN_ENDPOINT });
+
+		await clearOAuthSession();
+
+		expect(getOAuthMetadata()).toBeUndefined();
+		expect(await getOAuthRefreshToken()).toBeUndefined();
+		expect(await getToken()).toBe('tok_login');
+	});
+
+	it('getLocalUserInfo hands out the refreshed token and hides the oauth state', async () => {
+		vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse());
+		mkdirSync(GLOBAL_CONFIGS_FOLDER(), { recursive: true });
+		writeFileSync(AUTH_FILE_PATH(), JSON.stringify({ id: 'uid', username: 'me' }));
+		await seedSession({ expiresInMs: 30_000 });
+
+		const info = await getLocalUserInfo();
+
+		expect(info.token).toBe('tok_new');
+		expect(info).not.toHaveProperty('oauth');
+		expect(readAuthFile().oauth).toMatchObject({ issuer: ISSUER });
+	});
+});