API Key Format and Bearer Auth Explained

The header, exactly

The openai compatible api key format has two parts: the header and the key. The header is Authorization. Its value is the word Bearer, one space, and then your key:

CopyAuthorization: Bearer YOUR_KEY

The service reads the key from this header. Every endpoint (/v1/chat/completions, /v1/responses, /v1/models and the balance endpoints) takes the same header. SDKs build it for you from the api_key argument, so you rarely write it by hand. When you do, as in curl, formatting mistakes are the most common reason for a 401.

Why a bearer token works this way

The word bearer means that whoever bears (holds) the token is treated as its owner. The server does not ask for a second proof, a signature or a password. It reads the header, looks up the key and applies that account's balance and limits. This is why HTTPS matters: the header travels with every request, and TLS keeps it from being read on the network. This service is reached over https://, and you should never downgrade a client to plain http://.

The same property is why logging deserves care. Application logs, error trackers, reverse proxies and debugging tools often record request headers. Make sure the Authorization header is masked or dropped before it reaches a log line. A key in a log file is a key in every system that reads that file.

Finally, remember what the key cannot do. Do not assume a key can be limited to read-only use; treat every copy as full access to your balance. If you need to share access with a contractor, create a separate labelled key for them (up to 5 per account after a first top-up) and revoke it when the work ends.

What the key itself looks like

Do not assume a fixed length or prefix. Different providers use different patterns, and the safest habit is to treat the key as an opaque string: copy it from the API key page by selecting the whole line, and paste it unchanged. Do not validate it with a regular expression in your own code, because a pattern that fits today's keys may reject tomorrow's. Check only that the value exists and is not empty.

A key is a credential, not an identifier. It identifies your account to the server, and anyone holding it can spend your credit. Keep that in mind in everything below.

Common formatting mistakes

• No space after Bearer, or two spaces.
• Quotes inside the value. In a .env file, API_KEY="abc" is fine because the loader strips the quotes. In a raw header the quotes would become part of the key.
• A trailing newline. Keys copied from a file may carry a line break. Trim with .strip() in Python or .trim() in Node.
• The wrong header name. Some services use x-api-key. This one expects Authorization.
• Single quotes around a shell variable. -H 'Authorization: Bearer $API_KEY' sends the literal text. Use double quotes.
• An old key after regenerating. Reissuing invalidates the previous key immediately.

A defensive helper in Python:

Copyimport os
from openai import OpenAI

key = os.environ.get("API_KEY", "").strip()
if not key:
    raise SystemExit("API_KEY is not set")

client = OpenAI(base_url="https://api.openaicompatibleapikey.com/v1", api_key=key)
r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Reply with OK."}],
    max_tokens=5,
)
print(r.choices[0].message.content)

Linting is another cheap defense. A pre-commit hook or a CI step that scans for strings after the word Bearer, or for the name of your key variable followed by a literal value, catches most accidents before they leave your machine. Pair it with a rule that test fixtures use fake keys only, for example a value like test-key-not-real, so a real key never needs to appear in a file.

Storing the key safely

Pick the first option that fits your setup:

1. Environment variable set by your process manager, container runtime or CI secret store.
2. A .env file for local work, listed in .gitignore before the first commit.
3. A secret manager from your cloud or hosting platform for production.

Copyecho ".env" >> .gitignore
echo 'API_KEY=paste-your-key-here' > .env

# load it into the current shell
set -a; source .env; set +a

curl https://api.openaicompatibleapikey.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

Never put the key in front-end JavaScript, a mobile app bundle, a public repository, a screenshot or a chat message. A browser page that calls the API directly hands the key to every visitor. Call the API from your server and let the page talk to your server.

Copyconst key = process.env.API_KEY;
if (key === undefined || key === "") throw new Error("API_KEY is not set");

const res = await fetch("https://api.openaicompatibleapikey.com/v1/models", {
  headers: { Authorization: `Bearer ${key.trim()}` },
});
console.log(res.status);

Finding a key that already leaked

Keys escape more often through carelessness than through attacks. Some places to look before someone else does:

• Your git history. A search such as git log -p | grep -i "bearer" shows header literals that were committed. Also search for the name of the environment variable.
• Dotfiles and shell history. Commands typed with the key inline stay in ~/.bash_history or ~/.zsh_history. Prefer variables.
• Screenshots and recordings. Terminal captures in bug reports and tutorials often include a full command.
• Front-end bundles. Open your built JavaScript and search for the key itself. If the key is there, every visitor has it.
• Shared documents and chat. Pasted snippets in team chat stay searchable for a long time.

Hosting platforms and code hosts increasingly scan public repositories for secrets, but a scan is a safety net, not a plan. Assume a key that touched any of the places above is exposed and regenerate it.

Also keep a simple record of what the balance does. If you check X-Balance-USD once a day and note it, a sudden drop that your own traffic does not explain tells you about a leak sooner than any other signal. Pricing is $0.15 per 1M input tokens and $0.50 per 1M output tokens, so even heavy misuse of a modest balance is visible as a step in the number rather than a gradual drift.

Separate keys for separate jobs

After a first top-up, an account can hold up to 5 keys, each with a label. Use that: one key for production, one for staging, one for your laptop. If the laptop key ends up in a screenshot, you revoke that one and nothing else breaks. A trial key has the lower limits, 2 concurrent requests and 60 per minute; full keys allow 8 and 300.

If a key leaks

Act in this order:

1. Open the key page and regenerate the key, or revoke it if you keep several. The old key stops working at once. No support ticket is needed.
2. Put the new key into your secret store and redeploy.
3. Check the balance. Call GET /v1/balance or read the X-Balance-USD header and compare with what you expected. Usage you did not make shows as a balance lower than your own logs explain.
4. Remove the key from the place it leaked. If it was committed to git, rewriting history is not enough on its own, so treat the old key as burned either way.

Billing is by token at $0.15 per 1M input tokens and $0.50 per 1M output tokens, from prepaid credit that you load yourself, so exposure is capped by the balance. A simple habit limits it further: keep only the credit you expect to use soon on an exposed project. See the pricing page for top-ups, the documentation for the full list of headers, and the guide on using keys in uncensored programs for client-specific notes.

More guides

• Use an OpenAI-Compatible API Key in Cline
• How to use claude api key in uncensored programs