Seven steps,and your first request works.
A guide for your first time using an API. You will install a client, create your own API key, import it into CCSwitch, and send “hi” from Codex. Every step tells you what you should see.
https://api.blue-ring.xyz/v1Before you start, you need three things
This guide follows CCSwitch + Codex. If you only call the API, skip ahead to the optional chapter at the end.
Used to open the console, create keys, and check your own usage.
Codex + CCSwitch is recommended. Developers can use a terminal or Python directly.
Once imported from the console, CCSwitch hands this provider config to Codex.
When this chapter is done:Codex returns a normal reply, and the request shows up in your console usage page.
Install Codex and CCSwitch
Install first, configure second. Do not tune Codex defaults before a provider exists.
- Install CodexUse whatever install method your system offers. Do not build a complex config inside it yet.
- Install CCSwitchCCSwitch stores and switches providers, and runs on Windows, macOS, and Linux. Open the release page and download the package for your system.Download CCSwitch
- Both apps openSeeing the windows is enough. There is no API key yet, so nothing to send.
API-only developers can skip both tools and jump to “Call the API (optional)” at the end.
Sign up or sign in to Blue Ring
Keys and usage live in the console. Never ask anyone for a “public key”.
Open the Blue Ring console
Use the button to open the home page, then sign in or sign up. You land in your user console.
Open consoleA menu entry for API Keys is visible in the sidebar or on the page.
Create an API key and save it right away
A key is permission to call. Create one per device or per purpose, so a problem only costs you that one key.
- Open API KeysGo to the API Keys page in the console.
- Click create keyUse a name you will recognise, such as
codex-macordev-test. - Pick a groupIf groups or model groups are offered, choose by the capability you need. When unsure, keep the default.
- Copy the full key onceCopy it a single time after creation and store it in CCSwitch. Do not paste it into a group chat.
sk-••••••••••••••••••••••••HiddenNever put a full key in screenshots, Git, public issues, or chat history.
The key is in your password manager or client secure storage, and you know which device it belongs to.
Import the provider — no manual model setup
Prefer the console’s “Import to CC Switch” button. Only fill the fields below by hand when automatic import is unavailable.
Import to CC Switch under its actions. Names and keys in the figure are redacted.Find the key you just created and click “Import to CC Switch”, if the page offers it.
Allow the browser to open the app, then click import inside CCSwitch.
Give it a recognisable name, add and save, then click enable.
https://api.blue-ring.xyz/v1Keep /v1; do not point it at a request pathThe key you just createdDo not copy the surrounding quotes, and never use someone else’s keyFollow the client’s promptThe import path usually needs no extra setupClick enable inside CCSwitch
No terminal, and no model list request first. Once CCSwitch is configured, Codex uses this provider directly.
Look for the config you just imported in the CCSwitch provider list.
Do not create a second config — enable the one you have.
“In use” or an enabled state means Codex has the config.
The Blue Ring config in CCSwitch shows as enabled or in use.
Open Codex and type hi
With CCSwitch configured, Codex uses the provider you just enabled.
hi, and send. A normal reply means you can move on.Codex returns normal content for hi.
Check usage in the console
Once Codex replies normally, go back to the console and confirm the request and its cost.
Read the message itself, not just the client’s loading state.
Go back to the usage or records page in the console.
Seeing the request and its cost means the whole chain works.
You have a working Blue Ring setup
Switching models or clients later only means rechecking three things: Base URL, API Key, Model.
Content coming back from Codex means the client is connected.
The console usage list should show the request.
Confirm the call produced tokens or a charge.
Calling the API directly?
The model list, curl, and Python below are for API developers. If you followed CCSwitch + Codex, skip this.
This is not a required Codex step. Continue only if you want to call Blue Ring from a terminal, a script, or your own program.
export BLUE_RING_API_KEY="your-api-key"
curl "https://api.blue-ring.xyz/v1/models" \
-H "Authorization: Bearer $BLUE_RING_API_KEY"export BLUE_RING_API_KEY="your-api-key"
export BLUE_RING_MODEL="a model id from /v1/models"
curl "https://api.blue-ring.xyz/v1/responses" \
-H "Authorization: Bearer $BLUE_RING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$BLUE_RING_MODEL"'",
"input": "Introduce yourself in one sentence."
}'With the OpenAI SDK you only replace base_url and api_key.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.blue-ring.xyz/v1",
)
response = client.responses.create(
model="YOUR_MODEL_ID",
input="Hello from Blue Ring",
)
print(response.output_text)Troubleshooting: start with the status code
Confirm CCSwitch is enabled first, then work out whether it is the key, the path, or upstream.
401API_KEY_REQUIRED / unauthorized
The request carried no valid key. Check that Authorization: Bearer ... is present, that the environment variable is not empty, and that the client did not put the key in the wrong field.
404chat/completions not found
The main public path is /v1/responses. If the client can only send /v1/chat/completions, switch it to the Responses API / OpenAI Responses mode.
200A response, but the model is unavailable
On the CCSwitch path, reconfirm the provider is enabled. Calling the API directly? Request /v1/models and use a model ID it returns.
—The request hangs or times out
Test with the shortest possible text first. Rule out an extra proxy, a wrong streaming setting, or a doubled /v1 path before blaming upstream congestion.
↗Codex does nothing after the import
Recheck that the provider is enabled and that the base URL still contains /v1, then close and reopen Codex so it reads the new config.
API key safety: three hard rules
An API key is permission to spend on your account. Treat it like a password, not like ordinary config.
No full key in tutorials, group chats, tickets, or screen recordings.
Use environment variables or client secure storage; keep it out of the repo.
Delete the old key in the console, then create a new one and update the client.