What Are an API, an API Key, and a Token, Really? Settled in One Pass

"Just paste the token in" is a dangerous line of tutorial

When beginners wire up an API by following a tutorial, they often hit one line: "paste the token here." The problem is that this token could mean an API key, an OAuth access token, or just a text-counting unit in your model usage.

Those three are not the same thing at all.

An API is an agreed-on entrance between programs. An API key is a secret credential the service uses to identify the caller. A token, in a model context, can mean a text-counting unit; in an auth context, it can mean a credential carrying permissions and an expiry.

So when you see "fill in the token," don't copy it immediately. First confirm the variable name, the official page that creates it, the program that receives it, and what this value can do if it leaks. Get those four things clear and a lot of integration errors vanish before the request is even sent.

What actually happens in one API request

Web chat is an interface for people to operate; an API is an interface for programs to use. A minimal request usually has five parts:

1. Address: which endpoint the request goes to.
2. Method: e.g. GET or POST.
3. Headers: content type, auth method, and so on.
4. Body: the model, input and parameters.
5. Response: a status code, structured data, or an error.

Taking OpenAI's current official quickstart Responses API as an example, a curl request's structure can be written as:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "YOUR_CURRENT_MODEL_ID",
    "input": "Reply with only: connection successful"
  }'

YOUR_CURRENT_MODEL_ID is a placeholder — pick a currently available model from the official docs on the day you do this. Don't copy a possibly-retired model name from an old article.

This command also shouldn't write the real key directly inside it. The Authorization header reads from an environment variable.

Why an API key has to be treated like a password

Someone holding a valid API key could send requests within your project's quota, causing data risk, unexpected charges and service disruption.

The official safety advice includes: don't share your personal key, don't deploy a key to the browser or mobile, don't commit it to a code repo, and use environment variables or a secret-management service.

On macOS or Linux, the current terminal can set it temporarily:

export OPENAI_API_KEY="YOUR_REAL_KEY"

YOUR_REAL_KEY in this command is a placeholder. The real value should only be typed into your own controlled terminal — not into an article, a chat, a screenshot or a repo.

Official SDKs can usually read the credential from the OPENAI_API_KEY environment variable. Production also has to consider secret management, permission separation, rotation and usage monitoring — not just one shell line.

An environment variable is not a vault

Putting a key in an environment variable is safer than hard-coding it into source, but it doesn't mean the key is never visible.

Processes running under the same user, error logs, debug tools, terminal history and malicious scripts can still reach it. Real security means controlling all of these at once:

• Who can log into the machine.
• Which process can read the variable.
• Whether logs print the headers.
• Whether third-party tools upload config.
• Whether the key's permissions are too broad.
• Whether it can be revoked quickly after a leak.

Local development can start from environment variables; a production service should consider dedicated secret management based on risk.

The difference between the two kinds of token

Text tokens: used for model processing and billing

A model doesn't read all text as "one character" or "one word" — it splits the input into tokens. Input, output, caching and different capabilities may bill differently, and you must go by the current price page.

The same character count in Chinese, English, code and JSON doesn't necessarily produce the same token count. You can't estimate with "the article is a thousand words, so it must be a thousand tokens."

Auth tokens: used to prove permission

An OAuth access token, a session token, or another bearer token may represent a user's, an app's or a session's access rights. It usually has a scope and an expiry.

This kind of token has nothing to do with model text-counting. After a leak, treat it as a credential: revoke, rotate, and check for abnormal access.

When you see the word "token," look at whether it appears near "usage" and "input/output," or near "Authorization," "login" and "OAuth."

Don't assume ChatGPT web and the API share billing

The web product, the developer platform, the organization, the project and API usage may have different account entrances and billing rules.

Don't assume program calls are free just because you can chat on the web; and don't infer that a web subscription includes the same rights just because the API has a balance. Before integrating, check the current official product descriptions and usage pages separately.

Before your first call, finish seven preparations

1. Confirm the current endpoint, SDK and model from the official docs.
2. Create the key in your own official project.
3. Set a budget, limit or usage alert.
4. Put the key in a controlled environment, not in source.
5. Use the smallest input, with no private data.
6. Turn off unlimited auto-retry.
7. Be ready to view the status code, response body and usage records.

Don't do your first integration with a shared account of unknown origin, an SMS code service, or a cheap relay. They turn a technical problem into an account, privacy, stability and compliance problem.

How to tell your first call actually succeeded

The terminal printing some model text only proves the request got some kind of response. Full acceptance also looks at:

• The HTTP request went to the expected official address.
• The response is well-structured JSON.
• The returned content maps to the input.
• The request is logged under your own project.
• A reasonable record appears on the usage page.
• The log didn't print the full key.
• The program isn't retrying infinitely in the background.
• No data that shouldn't leave your machine is in the input.

If you're using a third-party SDK or proxy, also know whether it changes the endpoint, stores the request, or swaps the auth method.

How to read the common status codes

400: the request itself has a problem

Check the JSON format, required fields, model and parameters. Don't create a new key first.

401: identity can't be confirmed

Check whether the key is from the correct project, whether the environment variable reached the current process, whether there's whitespace around the value, and whether the header format is right.

If the key is suspected leaked, don't keep debugging the old key — revoke and rotate first.

403: identity recognized, but no matching permission

Check organization, project, model or region permissions. Don't read every 403 as insufficient balance.

429: too many requests, or quota-limited

Look at the current rate limit, balance and usage. Retries need backoff and a ceiling — not an endless loop.

5xx: the server side is temporarily off

Keep the request time and the necessary identifiers, and use limited retries. For an API with external side effects, also consider whether the previous request was in fact already processed.

A network error and an API error aren't the same thing. The former may not have gotten any HTTP response; the latter usually carries a status code and a structured error.

How to estimate the cost

A minimal cost model can be written as:

total cost =
  input token cost
  + output token cost
  + tool or media cost
  + extra requests from retries

The real rules may include caching, batching, images, audio, or different model prices. Numbers in an article go stale easily — check the official pricing on the day you use it.

The most effective way to control cost isn't just shortening the prompt. It also includes:

• Limiting the maximum output.
• Not resending irrelevant history over and over.
• Setting a ceiling on loops.
• Logging the model and usage for each task.
• Verifying with a minimal request first, then scaling the data.
• Setting a length boundary on user input.

What to do first after a key leaks

1. Revoke or rotate the key immediately.
2. Check current and historical usage.
3. Find everywhere the key appeared.
4. Clean source, logs, screenshots and deploy config.
5. If it reached Git history, treat it as a leak — not just deleting the current file.
6. Check whether programs still reference the old key.
7. Give the new key smaller permissions and a budget.

Don't first ask in a group chat "is this key still usable" — that causes a second leak.

After your first API call, don't just save that model reply. Confirm who the credential belongs to, where the cost is logged, and which address the data is sent to. With all three answers clear, then wire the call into automation.