Using an API Key: A Practical Walkthrough for Devs

When people search for "using an api key," they usually have two separate questions in mind: how do I attach this key to a request so the API actually accepts it, and how do I do that without leaking the key or breaking my app. Both questions matter equally — a key that works but leaks in your frontend code is worse than no key at all.

This article walks through the mechanics of using an API key correctly: where it goes in a request, how to store it, how to test it, and the mistakes that cause the most support tickets for API providers.

What "Using an API Key" Actually Means

An API key is a string that identifies your application (and often your account) to a server. When you send a request, you include the key so the server can:

• Confirm you're authorized to call the endpoint
• Track usage against your plan or quota
• Apply rate limits or permissions tied to that specific key

Using an API key is not the same as logging in with a username and password. There's no session, no cookie, no expiry dialog — the key itself is the credential, sent with every single request.

Where the Key Goes: Headers vs Query Strings

Most modern APIs expect the key in an HTTP header, not the URL. This matters because URLs get logged by proxies, browsers, and servers — a key in a query string ends up in places you don't control.

The most common pattern is an Authorization header with a Bearer prefix:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Summarize this changelog."}]
  }'

Some APIs use a custom header instead, like X-API-Key: your_key_here. Always check the provider's docs — there's no universal standard, and guessing wrong just gets you a 401.

Avoid putting keys in query strings (?api_key=abc123) unless the provider explicitly requires it. It's a leftover pattern from older APIs and it's genuinely less safe.

Using an API Key in JavaScript

In a Node.js backend, the pattern looks like this:

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4",
    max_tokens": 512,
    messages: [{ role: "user", content: "Summarize this changelog." }]
  })
});

const data = await response.json();
console.log(data);

Notice the key comes from process.env, not a hardcoded string. This is the single most important habit in this whole article — never write a key literally into a file that could end up in version control.

Never Put API Keys in Frontend Code

If your API key ends up in a browser bundle, it's public. Anyone can open dev tools, find it, and use it — including running up your bill or hitting your rate limits. This applies to any key tied to billing or usage, including keys used to call Claude through a service like SubToAPI.

The fix is almost always the same: put a small backend between your frontend and the API. Your frontend calls your own server, your server holds the key and calls the actual API. This is also where you'd add your own auth, rate limiting, or caching if needed.

Storing Keys Safely

A few practical rules that cover most real-world setups:

• Store keys in environment variables (.env files locally, secret managers in production)
• Add .env to .gitignore before your first commit, not after you notice the key in a diff
• Use different keys for development, staging, and production so a leaked dev key doesn't touch production data
• Rotate keys periodically and immediately after any suspected exposure
• If your provider supports scoped or per-project keys, use them instead of one master key everywhere

Testing a Key Before Wiring Up Your App

Before writing application code, confirm the key works with a plain curl request. This isolates whether a problem is your code or your credentials.

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-4", "max_tokens": 50, "messages": [{"role": "user", "content": "ping"}]}'

If this returns a proper JSON response with content, the key is valid and correctly formatted. If you get a 401, double-check the header name and prefix. If you get a 403, the key is probably valid but lacks permission for that specific resource.

Common Errors When Using an API Key

• 401 Unauthorized — the key is missing, malformed, or wrong. Check for typos, extra whitespace, or an expired key.
• 403 Forbidden — the key is valid but doesn't have access to this endpoint or resource.
• 429 Too Many Requests — you've hit a rate limit. Check the response headers for retry timing.
• Key works locally but fails in production — almost always an environment variable that wasn't set on the deployed server.

Where SubToAPI Fits

If you're building on top of Claude and want a straightforward key-based workflow instead of managing OAuth flows or session tokens, SubToAPI turns your existing Claude access into an HTTPS API with standard sub_live_... keys. You generate a key in the dashboard, use it exactly like the examples above, and get streaming, tool use, and usage metadata without extra plumbing. Check the quickstart to see a full working example, or browse pricing if you're evaluating options for a team.

Questions

Do I need a different API key for every project? It's a good practice, not a strict requirement. Separate keys per project or environment make it easier to track usage, revoke access without affecting other apps, and limit damage if one key leaks.

Can I use an API key directly in a mobile or browser app? You can, but you shouldn't for any key tied to billing or private data. Route requests through your own backend so the key never reaches client-side code.

What's the difference between an API key and a bearer token? In practice, they're often the same thing sent the same way — as a Bearer value in the Authorization header. The distinction matters more for OAuth-based tokens, which usually expire and get refreshed, unlike most static API keys.