How to Use an API Key: A Step-by-Step Guide

An API key is a token you send with every request to prove your application is allowed to use a service. In almost all modern APIs, you use it by adding it to an HTTP header — most commonly Authorization: Bearer YOUR_KEY — on every request you make. You get the key from the provider's dashboard after signing up, keep it secret, and pass it along with your requests instead of a username and password.

That's the short answer. The rest of this guide covers the details that actually trip people up: where exactly the key goes, how to test it, what errors mean, and how to avoid the mistakes that get keys leaked or revoked.

Step 1: Get Your API Key

Almost every API provider issues keys from a dashboard after you sign up. The key usually looks like a long random string, sometimes with a prefix that identifies the service or environment, for example sub_live_... or sk-.... That prefix is intentional — it lets automated secret scanners and support teams recognize which service a leaked key belongs to.

When you generate a key, copy it immediately and store it somewhere safe. Most dashboards only show the full key once, right after creation. If you lose it, you'll need to revoke it and generate a new one — there's rarely a way to retrieve a lost key later.

Step 2: Send It in the Right Place

There are three common patterns, and using the wrong one is the most frequent cause of "invalid API key" errors.

Authorization header (most common today):

curl https://api.example.com/v1/resource \
  -H "Authorization: Bearer YOUR_API_KEY"

Custom header (some APIs use their own header name):

curl https://api.example.com/v1/resource \
  -H "X-API-Key: YOUR_API_KEY"

Query parameter (older or simpler APIs):

https://api.example.com/v1/resource?api_key=YOUR_API_KEY

Always check the provider's docs for the exact format — headers are case-insensitive but the scheme name (Bearer, Token, etc.) usually isn't optional, and typos there are a common source of 401 errors.

Step 3: Make Your First Request

Once you know the header format, test with a minimal request before wiring anything into your app. For example, calling SubToAPI's messages endpoint looks like this:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "Say hello in one sentence." }
    ]
  }'

The same pattern applies in JavaScript:

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: 256,
    messages: [{ role: "user", content: "Say hello in one sentence." }]
  })
});

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

If this works, you've confirmed the key is valid and correctly formatted — the rest is just building out your application logic. The quickstart walks through the full setup, including streaming responses and tool calls, if you need more than a single request.

Step 4: Store the Key Safely

Never hardcode an API key directly in source code that gets committed to version control. Use environment variables instead:

export SUBTOAPI_KEY="sub_live_xxxxxxxxxxxxxxxx"

Then read it in your code with process.env.SUBTOAPI_KEY (Node.js) or os.environ["SUBTOAPI_KEY"] (Python). Add .env files to .gitignore, and if you're deploying, use your platform's secrets manager (Vercel environment variables, AWS Secrets Manager, GitHub Actions secrets, etc.) rather than pasting keys into config files.

If a key ever ends up in a public repo, treat it as compromised: revoke it in the dashboard and generate a new one immediately, even if you delete the commit — Git history and cached copies can persist.

Common Errors and What They Mean

• 401 Unauthorized — the key is missing, malformed, or wrong. Double-check the header name and scheme (Bearer vs no prefix).
• 403 Forbidden — the key is valid but doesn't have permission for this action (wrong scope, wrong plan tier, or the resource belongs to another account).
• 429 Too Many Requests — you've hit a rate limit. Check the response headers for retry timing and add backoff logic.
• Key works locally but not in production — usually an environment variable that wasn't set on the deployed server, or a mismatch between test and live keys.

Using Multiple Keys for Different Environments

Most providers let you create separate keys for development, staging, and production. This is worth doing from day one: it means a leaked development key doesn't expose production traffic, and you can revoke or rotate one environment without breaking the others. On SubToAPI, each application gets its own sub_live_... key from the dashboard, and usage per key is tracked separately, which makes it easy to see which app or environment is generating traffic. See pricing for how keys map to seats and plans if you're setting this up for a team.

Questions

Do I need to include the API key on every request? Yes. APIs are stateless by default — the server doesn't remember who you are between calls, so the key (or token) must be sent with each request, typically in the Authorization header.

What's the difference between an API key and an OAuth token? An API key is usually a long-lived, static credential tied to an account or application. OAuth tokens are typically short-lived, scoped to specific permissions, and refreshed periodically. API keys are simpler to use; OAuth is more common when a service acts on behalf of an individual user with fine-grained permissions.

Can I use the same API key in multiple applications? Technically yes, but it's not recommended. Using separate keys per application makes it easier to track usage, revoke access if one app is compromised, and enforce per-app rate limits without affecting your other integrations.