Codex CLI invalid_api_key usually means the CLI is not sending the API key expected by the selected provider, or it is sending the key to the wrong Base URL. Check that your API key belongs to the same platform as your Base URL, that your custom provider config points to the correct endpoint, that the environment variable name matches the provider config, and that /v1/models works before running a real Codex task.
What invalid_api_key means in Codex CLI
When Codex CLI reports invalid_api_key, it means the CLI sent a request with an API key that the selected provider rejected. This is an HTTP 401 error at the network level.
The two most common causes are:
- The API key was sent to the wrong Base URL — the provider at that endpoint does not recognise the key.
- The environment variable name does not match the name declared in the custom provider config.
Less common causes include a revoked or rotated key, a key created under a different account, insufficient credits, or a model the key does not have permission to access.
The fastest checklist
Work through these five checks in order:
- Confirm the Base URL belongs to the same provider as the API key.
- Confirm the environment variable name matches env_key in the custom provider config.
- Confirm the API key is active and has not been rotated.
- Confirm the account has enough prepaid credits.
- Confirm /v1/models returns a model list with the key.
API key vs Base URL mismatch
An API key from Platform A only works with the Base URL of Platform A. If you configure Codex CLI with a key from RutaAPI but point it to a different Base URL, the request is rejected with 401 invalid_api_key.
The correct RutaAPI Base URL is https://api.rutaapi.com/v1. Do not use https://rutaapi.com, https://app.rutaapi.com, or any path that ends in /chat/completions as the Base URL — those are not the API root.
How custom providers work in Codex CLI
OpenAI Codex supports custom model providers. A provider defines how Codex connects to a model: the Base URL, the wire API format, authentication and optional HTTP headers.
A provider is defined in the config.toml file under the [model_providers] section. Each provider has a name and a base_url. Codex CLI reads the model_provider field in the global section and looks up the corresponding provider entry.
| Error | Common meaning | First check | |
|---|---|---|---|
| 401 invalid_api_key | Wrong key, missing key, wrong env var, or key sent to wrong Base URL. | Check env_key and Base URL. | Confirm the key belongs to the same provider as the Base URL. Verify env variable name matches env_key in config.toml. |
| 403 | Key exists but lacks permission, credits, group access or model access. | Check account status, credits and model permissions. | Verify the model appears in /v1/models. Check prepaid credits. Contact support if permissions are unexpected. |
| 404 | Model or route not found. | Run /v1/models and copy a returned model name. | Do not guess the model name. Use the exact id string from /v1/models as MODEL_NAME. |
| 429 | Rate limit or concurrency limit. | Reduce concurrency or retry later. | Lower the number of concurrent Codex tasks. Check account-level rate limits. |
| 503 | Provider or route temporarily unavailable. | Try short request, check model availability. | Contact support if persistent. Verify credits and account status. |
First checks before running a Codex task
Before opening a Codex session, work through these five checks to rule out configuration issues:
- Confirm the Base URL belongs to the same provider as the API key.
- Confirm the environment variable name matches env_key in config.toml.
- Confirm the API key is active and has not been rotated.
- Confirm the account has enough prepaid credits.
- Confirm /v1/models returns a model list with the key.
Will a failed Codex request be billed?
A 401 invalid_api_key or authentication error means the request never reached the upstream model — no tokens were generated and no billable usage should be recorded.
Check your usage logs after the error. If tokens were counted despite the 401, review the specific usage log for that request. If you are unsure whether a failed request was billed, contact support with the request time, model name, error code and any request ID from the response headers.
Step-by-step Codex CLI troubleshooting
1. Verify the Base URL
The Base URL must end in /v1 and must belong to the same provider as the API key. The correct RutaAPI Base URL is https://api.rutaapi.com/v1.
2. Check the environment variable
Export the API key with the exact name declared in env_key in config.toml. For RutaAPI: export RUTAAPI_API_KEY="YOUR_RUTAAPI_KEY"
3. Run /v1/models
Confirm the key is valid: curl https://api.rutaapi.com/v1/models -H "Authorization: Bearer YOUR_RUTAAPI_KEY"
4. Copy the exact model name
Use one of the id values from the /v1/models response as MODEL_NAME. Do not guess.
5. Try a short request first
Before sending a full Codex task, send a simple chat completions request to confirm end-to-end connectivity.
6. Contact support if it persists
Include: request time (UTC), model name, error code, Base URL, request ID if available. Do not share your full API key.
When RutaAPI may help
RutaAPI may be a good fit for troubleshooting Codex CLI invalid_api_key errors when:
- You need an OpenAI-compatible Base URL to rule out Base URL configuration issues.
- You want prepaid credits instead of a complex billing setup — making it easier to track usage and top up.
- You want to create and manage API keys from a dashboard to verify key validity quickly.
- You need Codex CLI setup docs to cross-check configuration.
- You want to verify available models with /v1/models before sending a Codex task.
- You want usage visibility — seeing which models were called, request counts and credit usage.
Create a RutaAPI API key to test the Base URL, /v1/models and verify your configuration.
When RutaAPI may not fix the issue
RutaAPI is an API gateway — it can help rule out configuration issues, but it cannot guarantee a fix for all Codex CLI authentication errors:
- Codex CLI may have changed config behaviour in a newer version — verify against current Codex docs.
- If the selected model is unavailable upstream, the gateway cannot force availability.
- If Codex CLI does not support custom providers in your version, a different Base URL will not help.
- If the API key belongs to another provider, it will not work with RutaAPI's Base URL.
- RutaAPI is not an official OpenAI service and cannot control Codex CLI's internal behaviour.
- No API gateway can guarantee compatibility with every Codex CLI version or configuration.
FAQ
What does Codex CLI invalid_api_key mean?
It means the API key sent by Codex CLI was rejected by the provider. The CLI received an HTTP 401 response. Common causes are a wrong key, a key sent to the wrong Base URL, a mismatched environment variable name, or a revoked key.
Is invalid_api_key always a bad API key?
Not always. The key may be correct but sent to the wrong Base URL — for example, a RutaAPI key sent to a different provider's endpoint. Always check both the key and the Base URL together.
Can a wrong Base URL cause invalid_api_key?
Yes. If the Base URL belongs to a different provider than the API key, the provider rejects the key with 401. The key and Base URL must come from the same platform.
Should RutaAPI Base URL include /v1?
Yes. The correct RutaAPI Base URL is https://api.rutaapi.com/v1 — it must include /v1. Without it, you are pointing to a non-API endpoint and will get 404 or 401 errors.
Which environment variable should I set?
Set the variable name that matches the env_key declared in the [model_providers.rutaapi] section of your config.toml. For RutaAPI this is typically RUTAAPI_API_KEY. Export it before running Codex CLI.
How do I verify my RutaAPI key?
Call GET /v1/models with the Authorization Bearer header. A 200 response with a model list means the key is valid. A 401 response means the key is missing, wrong or revoked.
How do I choose MODEL_NAME?
Run GET /v1/models and use one of the model id values from the response as MODEL_NAME in config.toml. Do not guess the model name — model identifiers differ between providers.
What does 401 mean?
HTTP 401 Unauthorized means the API key is missing, wrong or not accepted by the provider. Verify the key belongs to the same platform as the Base URL.
What does 403 mean?
HTTP 403 Forbidden means the key exists but lacks permission. Check that your account has enough prepaid credits and that the model is enabled for your key.
What does 404 model not found mean?
HTTP 404 means the model name is not recognised at that endpoint. Run /v1/models and use one of the returned model id values as MODEL_NAME. Do not guess the name.
Can RutaAPI guarantee Codex compatibility?
No. RutaAPI is an OpenAI-compatible API gateway — it implements the OpenAI wire format. Codex CLI compatibility depends on Codex CLI's own support for custom providers, which may vary by version.
Is RutaAPI an official OpenAI service?
No. RutaAPI is an OpenAI-compatible API gateway operated by BDR FIDUCIARY LLC. It is not an official service of OpenAI, Anthropic, Google or Microsoft.
Should I paste my API key into screenshots?
No. Never share your full API key in screenshots, forum posts, support tickets or any public or shared channel. If your key is ever exposed, rotate it immediately from the dashboard.
What should I send to support?
Include: request time (UTC), model name, error code, Base URL, any request ID from response headers, and approximate request size. Do not share your full API key. Describe the key prefix if needed.