Fix Codex "unexpected status 401 Unauthorized"

Other forms of the same error

• unexpected status 401 Unauthorized: {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}, url: https://www.ccsub.net/api/v1/responses
• Missing environment variable: `OPENAI_API_KEY`.

Read the url first, then the message

Codex formats HTTP errors as unexpected status 401 Unauthorized: <response body>, url: <request URL>. That trailing url tells you where the request actually went:

• https://www.ccsub.net/api/v1/responses — the request reached CCSub and the key was refused. Read the message in the body.
• Any other host — Codex isn't using your CCSub settings and is still talking to its default provider. Swapping keys won't help; fix the config file.

CCSub only has two 401 messages. Missing or invalid API key means the request had no key or the value didn't start with sk- (a ChatGPT login token doesn't). Invalid or disabled API key means it carried an sk- value that doesn't exist, was truncated, or was disabled or deleted in the dashboard.

A config.toml that works with CCSub

Codex's configuration reference supports custom model providers: base_url is the endpoint, env_key names the environment variable that holds the API key, and wire_api accepts responses (the only supported value). For CCSub:

# ~/.codex/config.toml
model = "gpt-5.5"
model_provider = "ccsub"

[model_providers.ccsub]
name = "CCSub"
base_url = "https://www.ccsub.net/api/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Then:

export OPENAI_API_KEY="sk-your-key"
codex

env_key holds the name of an environment variable, not the key itself. This guide uses OPENAI_API_KEY to match the install docs. If that variable is already taken by another service, rename it in both places (env_key and the export line), for example to CCSUB_API_KEY, so you always know which credential Codex used. Set model to any model ID from the CCSub model list.

Four mistakes that cause this

Top-level keys placed under a table. In TOML, every key after a [model_providers.ccsub] header belongs to that table. If you append model_provider = "ccsub" at the bottom of the file, it becomes a field of the provider table, Codex never sees it, and it falls back to the default provider — which is why the url in the error isn't ccsub.net. Keep model, model_provider, and openai_base_url at the very top, before any [...] header. The Codex issue tracker has a case where openai_base_url was ignored for exactly this reason.

The variable exists, but not in the Codex process. export only applies to the current shell and programs started from it. Codex Desktop opened from the Dock or Start menu, or an editor extension, usually can't see variables from ~/.zshrc. You'll get Missing environment variable or a 401. Prove the key works by exporting it and running codex in a terminal, then sort out the desktop app's environment. On Windows, after [System.Environment]::SetEnvironmentVariable, close every terminal and Codex window before trying again.

A switcher tool rewrote your config. Tools like CC Switch rewrite ~/.codex/config.toml and auth.json when you switch providers. Edit by hand and then click switch in the tool, and your changes can be overwritten. Pick one way of managing the config and stick to it.

The key is truncated or disabled. A CCSub key is sk- plus 64 hex characters, 67 in total. The API Keys page keeps the full key so you can copy it again any time, and a disabled key can be re-enabled there. To test the key without Codex in the way (one tiny billable request):

curl -sS -w '\n%{http_code}\n' https://www.ccsub.net/api/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.5","input":"hi"}'

A 200 means the key is good and the issue is your Codex config. A 401 means try a different key.

FAQ

Related errors

• API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}The key never arrived or it's the wrong one. Check /status, re-copy the full key from the dashboard, and unset any leftover ANTHROPIC_API_KEY.
• stream disconnected before completion: stream closed before response.completedThe stream dropped before it finished. Make sure base_url is https://www.ccsub.net/api/v1, take local proxies out of the path, shorten very long turns, and raise stream_max_retries on the provider.
• There's an issue with the selected model (claude-opus-6). It may not exist or you may not have access to it. Run /model to pick a different model.The model ID is wrong — use an id from /api/v1/models (hyphenated). If every model fails and the response is an HTML page, your base URL is wrong instead.