SpyBara
Go Premium

auth.md 2026-07-08 02:01 UTC to 2026-07-14 17:03 UTC

106 added, 104 removed.

2026
Wed 15 19:58 Tue 14 17:03 Wed 8 02:01 Mon 6 22:58

Authentication

OpenAI authentication

Codex supports two ways to sign in when using OpenAI models:

  • Sign in with ChatGPT for subscription access
  • Sign in with an API key for usage-based access

The ChatGPT desktop app, Codex CLI, and IDE extension support both sign-in methods for local work. Codex cloud requires signing in with ChatGPT.

Your sign-in method also determines which admin controls and data-handling policies apply.

  • When you sign in with ChatGPT, Codex usage follows your ChatGPT workspace permissions, role-based access control (RBAC), and ChatGPT Enterprise retention and residency settings.
  • With an API key, usage follows your API organization's retention and data-sharing settings instead.

For managed workspaces, authentication is only one layer of access. Workspace membership and provisioning determine who can sign in, while seats and workspace roles determine which product surfaces and features they can use. For local work in the ChatGPT desktop app, Codex CLI, or IDE extension, permission profiles constrain what the agent can do on the device. See Groups and provisioning and Roles and workspace permissions to plan those controls.

Sign in with ChatGPT

When you sign in with ChatGPT from the ChatGPT desktop app, Codex CLI, or IDE extension, the sign-in flow opens a browser window. After you sign in, the browser returns your credentials to Codex.

ChatGPT desktop app

On the signed-out screen, select Continue to sign in, then complete the browser flow.

Sign in with an API key

You can also sign in to the ChatGPT desktop app, Codex CLI, or IDE extension with an API key. Get your API key from the OpenAI dashboard.

ChatGPT desktop app

On the signed-out screen, select Sign in another way, enter your key, then select Continue.

OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the API pricing page.

API key authentication supports local Codex workflows, but some features that rely on ChatGPT workspace access or cloud services are limited or unavailable. Compare support by plan in Feature availability.

When you sign in with an API key, Codex uses standard API pricing instead of included ChatGPT plan credits.

Use API key authentication for programmatic Codex CLI workflows, such as CI/CD jobs. Don't expose Codex execution in untrusted or public environments.

Check authentication or sign out

Open the profile menu to see the active account or API key status. Select Log out to clear the current credentials.

Use Codex access tokens for enterprise automation

In ChatGPT Enterprise workspaces, admins can grant the access token permission so permitted members can create Codex access tokens for trusted, non-interactive Codex local workflows. Use an access token when automation needs ChatGPT workspace access, ChatGPT-managed Codex entitlements, or enterprise workspace controls without a browser sign-in.

Access tokens are intended for trusted scripts, schedulers, and private CI runners. For general OpenAI API calls, continue to use Platform API keys.

For setup steps, permissions, rotation, and revocation guidance, see Access tokens.

Secure your Codex cloud account

Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).

If you use a social login provider (Google, Microsoft, Apple), you aren't required to enable MFA on your ChatGPT account, but you can set it up with your social login provider.

For setup instructions, see:

If you access ChatGPT through single sign-on (SSO), your organization's SSO administrator should enforce MFA for all users.

If you log in using an email and password, you must set up MFA on your account before accessing Codex cloud.

If your account supports more than one login method and one of them is email and password, you must set up MFA before accessing Codex, even if you sign in another way.

Login caching

When you sign in to the ChatGPT desktop app, Codex CLI, or IDE extension using either ChatGPT or an API key, your login details are cached and reused. The CLI and extension share the same cached login details. If you log out from either one, you'll need to sign in again the next time you start the CLI or extension.

Codex caches login details locally in a plaintext file at ~/.codex/auth.json or in your OS-specific credential store.

For sign in with ChatGPT sessions, Codex refreshes tokens automatically during use before they expire, so active sessions usually continue without requiring another browser login.

Credential storage

Use cli_auth_credentials_store to control where the Codex CLI stores cached credentials:

# file | keyring | auto
cli_auth_credentials_store = "keyring"
  • file stores credentials in auth.json under CODEX_HOME (defaults to ~/.codex).
  • keyring stores credentials in your operating system credential store.
  • auto uses the OS credential store when available, otherwise falls back to auth.json.

See the configuration reference for the complete config.toml schema.

If you use file-based storage, treat ~/.codex/auth.json like a password: it contains access tokens. Don't commit it, paste it into tickets, or share it in chat.

Enforce a login method or workspace

In managed environments, admins may restrict how users are allowed to authenticate:

# Only allow ChatGPT login or only allow API key login.
forced_login_method = "chatgpt" # or "api"

# When using ChatGPT login, restrict users to a specific workspace.
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

If the active credentials don't match the configured restrictions, Codex logs the user out and exits.

These settings are commonly applied via managed configuration rather than per-user setup. See Managed configuration.

Alternative model providers

When you define a custom model provider in your configuration file, you can choose one of these authentication methods:

  • OpenAI authentication: Set requires_openai_auth = true to use OpenAI authentication. You can then sign in with ChatGPT or an API key. This is useful when you access OpenAI models through an LLM proxy server. When requires_openai_auth = true, Codex ignores env_key.
  • Environment variable authentication: Set env_key = "<ENV_VARIABLE_NAME>" to use a provider-specific API key from the local environment variable named <ENV_VARIABLE_NAME>.
  • No authentication: If you don't set requires_openai_auth (or set it to false) and you don't set env_key, Codex assumes the provider doesn't require authentication. This is useful for local models.