Blog / November 17, 2026

API Key Test: How to Check if Your Key Works

Learn how to run an API key test with one request, read 200, 401 and 403 responses, and fix authentication errors quickly.

API Key Test: How to Check if Your Key Works
On this page

Your integration returned a 401 at 2 a.m. The same request worked from your terminal an hour earlier, against the same endpoint, with what looked like the same key. Nothing in the code changed between those two moments. What changed is which copy of the credential the running process was holding.

That gap is where most API key test routines fall apart. A team confirms the key exists, sends one request by hand, sees a 200, and marks the integration verified. The check proves that one endpoint accepted one input at one instant. It doesn't prove the key is scoped correctly, that it stays out of logs, or that it fails cleanly once revoked.

The surface keeps growing. Postman's 2025 State of the API Report found that 82% of organizations had adopted some level of API-first development in 2025, including 25% that were fully API-first. Every one of those integrations authenticates with something, and most of those calls carry a credential someone pasted into a header or a secrets store.

Table of Contents

  • Send One Request to Confirm Your Key Works
  • Reading Status Codes and What Each One Means
  • Fixing Authentication Errors One Cause at a Time
    • When one machine disagrees with the rest
  • Checking Where Your Key Leaks Beyond the Response
  • Build a Repeatable Key Test Checklist
    • Turn the checklist into a release gate
    • Rotation belongs in the same matrix
  • Run the Key Test on Your Own Account Today

Send One Request to Confirm Your Key Works

A first request is a baseline, not a verdict. You need one known-good call from this key before a later failure tells you anything useful.

Step 1. Copy the key from your account. Sign in at app.richapi.ai and copy the key the dashboard shows. Take the whole string in one action. A truncated paste fails in a way that looks like a permissions problem, not a clipboard problem.

Step 2. Put the key only in the x-api-key header, and set Content-Type. RichAPI authenticates with an x-api-key header. Find Personal Email also expects Content-Type: application/json. Keep the key out of the URL. Query strings land in access logs, proxy logs, browser history, and analytics dashboards. Revoking the key later does not pull a copy that already sits in a log aggregator.

Step 3. POST to Find Personal Email. Send a POST to https://api.richapi.ai/api/v1/find_personal_email. Build the body from one accepted input shape in the endpoint documentation, using a contact record you own. You already know the right email, so a plausible but wrong answer stands out.

bash
read -s RICHAPI_KEY
curl -sS https://api.richapi.ai/api/v1/find_personal_email \
  -X POST \
  -H "x-api-key: $RICHAPI_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  -w '\nHTTP %{http_code}\n'

The -w flag prints the status code. Many clients hide that code behind a success banner, and the code is the part you can compare across runs.

Step 4. Read the success field. The JSON body carries a success field. success true means this key authenticated and this endpoint accepted this input. It does not mean every endpoint on the account is open to that key, and it does not mean the input was a good one.

A 200 is only half the test. On the same run, search logs, CI output, and agent transcripts for the key string. The key belongs in the x-api-key header and nowhere else. Treat that string as a canary: if it shows up in a shell transcript, a ticket, or a model log, the request that returned 200 still failed the credential check.

A three-step guide on how to test a new API key using a curl request command.

Store the key in an environment variable or a secrets manager rather than pasting it into a command. That keeps it out of shell history, out of the snippet someone drops into a ticket, and out of the diff you push. If you'd rather build the same call in a GUI and keep it as a saved collection with an environment variable, the Postman API testing walkthrough from GoReplay covers the request builder and saved examples. When the client itself is the suspect, the hosted API demo sends the same request outside your codebase, which separates a bad key from a bad client.

Keep the recorded status, the success value, and the canary result together. A clean header and a clean search are what make this baseline worth trusting.

Reading Status Codes and What Each One Means

The two results that look most alike send people in opposite directions: a 200 whose body says success false, and a 401. Only one of them is about your credential.

A 200 with success false means the key was accepted and the request was rejected. Authentication passed. The input didn't. Look at the field names and the input shape the endpoint documents, because swapping the key won't fix a body problem, and rotating a working credential to chase an input error costs an afternoon.

A 401 means the key is missing, wrong or revoked. The fix is a valid key in the x-api-key header, nothing more creative than that. A 403 means the endpoint isn't available on the plan for that key. That's a scope answer rather than a credential answer: call GET /api/v1/my-endpoints to see which endpoints the key can use, then point the test at one of them.

StatusWhat It MeansWhat to Do Next
200 OK with success trueKey accepted and request processedTest passes; move on to the full test matrix
200 OK with success falseKey accepted but the request or input was rejectedCheck the body and input shape, not the key
401 UnauthorizedKey missing, wrong or revokedSend a valid key in the x-api-key header
403 ForbiddenEndpoint not available on the plan for this keyCall GET /api/v1/my-endpoints to list allowed endpoints
429 Too Many RequestsRate limit hit for this key's quotaSlow down, confirm the quota, check throttling is deterministic
5xx Server errorProblem on the provider side, not the keyRetry with backoff, then check status before blaming the key

A 429 is the code people misread most often, because authenticated and unauthenticated traffic usually run on different quotas. NIST's NVD developer documentation documents 5 requests per rolling 30 seconds without a key versus 50 with a key, which is exactly why a resilience test has to model both quota tiers separately instead of treating every throttle as a credential failure.

Server errors are the other false alarm. A 5xx points at the provider, so retry with backoff and check the status page before you touch the key. Regenerating credentials to fix someone else's outage is how working integrations break.

The clean pass: repeated 200 responses with success true, no 429 at your normal request rate, and a 401 the moment you swap in a revoked key.

Fixing Authentication Errors One Cause at a Time

Most 401s come from the key string, not from the account. The credential picks up a trailing newline from a terminal copy, a leading space from a double click, or a missing last four characters from a truncated paste, and the API rejects all three the same way.

SymptomLikely CauseFix
401 right after copying a keyExtra spaces, a newline or a truncated value pasted with the keyRe-copy from the dashboard and paste without trailing characters
401 on one machine onlyOld key still set in a local environment variableUpdate the variable and restart the process
401 after it worked yesterdayKey revoked or rotatedCopy the current key and update every consumer
Key ignored by the serverKey sent in a query string or body instead of the headerMove it to the x-api-key header
403 on a working keyEndpoint not on the plan for this keyCheck GET /api/v1/my-endpoints and use an allowed endpoint

Work through it in this order, because each step rules out a category rather than a single guess.

  1. Check the header name and location. It's x-api-key, not Authorization, not X-API-KEY with a capital X if your gateway is case-sensitive, and not a query parameter. Some servers ignore a key sent in the wrong place; others reject it.
  2. Confirm Content-Type is application/json. A JSON endpoint that receives form-encoded data can fail before it ever validates the key.
  3. Compare the first and last characters against the dashboard. Two characters are enough to spot a truncation or a newline.
  4. Replace the key with a fresh copy and retest. Don't trim and retry the same string. Paste a new one.
  5. If the 401 survives, treat the key as revoked. Check whether a teammate rotated it, a deploy replaced the secret, or a scheduled rotation job ran early.

When one machine disagrees with the rest

The failure that eats the most time is the single server holding a stale value. Your laptop works, staging works, and one production instance fails, because its environment file, container secret or systemd unit still carries the previous key and nothing reloaded the process after the last rotation. Compare the actual runtime value on the failing host, not the value in your config repository.

A key that worked yesterday and fails today has almost always been revoked or rotated. Confirm the fix by rerunning the single request from earlier and looking for a 200 with success true, then rerun the negative case with the old value to prove it now fails.

Checking Where Your Key Leaks Beyond the Response

A staging job returns 200, success is true, and the on-call channel goes quiet. That response only proves the key authenticated. It says nothing about whether the value stayed inside the x-api-key header while the request moved through logs, CI output, and an agent transcript.

Use a disposable canary key for that second half of the test. Issue a key you will revoke after the run, send it through every path the integration uses (REST client, MCP tool call, bulk job, webhook retry), then search for that string everywhere the traffic landed.

Start with the cheap failures, because a broken error path is where keys leak first. Send a missing key, a malformed key, and a revoked key. Each should return a clean 401: no key in the message, no stack trace, and no partial payload.

A laptop and smartphone on a desk showing API test requests alongside network service connection diagrams.

A header value shows up in ordinary places:

  • URLs and query strings, including redirects your HTTP client follows.
  • Request and response logs, plus the error tracker that stores request context.
  • Traces and analytics, where the header set gets attached to spans by default.
  • CI artifacts and test reports that print the environment.
  • Support tickets and chat threads that contain a pasted curl command.
  • AI-agent prompts and tool-call transcripts, which outlive the terminal session.

The OWASP GenAI incident roundup reported that a 2025 DeepSeek exposure included API keys and user metadata across more than one million records. The same roundup cited MIT's AI incident database entries covering more than 143,000 publicly accessible conversations that held sensitive material such as API keys. Those figures are reported exposures, not a controlled prevalence study. They still show the direction of travel: the credential leaves the client.

Shipping rule: a key value that appears anywhere other than the x-api-key header is a failed test, even when the response was a perfect 200.

Run the search as a routine after every pass. Grep log directories, CI artifacts, and agent transcripts for the canary prefix, and treat every hit as a defect with the same severity as a 401 you cannot explain. Your key's fate also depends on the other side of the request, so include the RichAPI security page in that vendor review.

Build a Repeatable Key Test Checklist

A single request is a smoke test. A matrix is what stops the same failure from returning next quarter, and it's the difference between testing a key and testing the system that holds it.

The stakes show up in survey data. A 2025 global API-security survey reported that 57% of organizations had experienced at least one data breach caused by API exploitation during the preceding two years.

Run every line below in one job on every build:

  • Known-good key with a fixed payload. Assert the status, the response schema and the scope, not just that something came back.
  • Missing key. Expect 401, with no payload and no trace in the body.
  • Malformed key. Expect 401, and confirm the value you sent isn't reflected back.
  • Revoked key. Generate one, revoke it, retest immediately. This is the only case that proves revocation propagates.
  • Expired key and wrong-environment key, such as a staging credential against production. Both should fail closed.
  • Valid key lacking endpoint permission. Expect the documented refusal with no partial data in the error.
  • Replay and burst cases. Fire the same request twice, then burst past the quota. Throttling should be deterministic, not random.
  • Cross-tenant read. Request another account's object with a valid key. It must fail, and it must fail loudly enough to be logged.
A table outlining a repeatable test checklist for API keys, including scenarios for valid, missing, invalid, and expired keys.

Turn the checklist into a release gate

The gate is 100% pass on authentication, authorization, tenant-isolation and secret-redaction assertions across several runs, not one green build. The U.S. Department of Defense API guidance recommends testing authentication at the unit, integration and application layers, and names the tools to do it: Postman, OWASP ZAP, Burp Suite, JMeter and Nessus. The same guidance calls for least privilege, secure secret storage, centralized auditing of failures and credential rotation.

Rotation belongs in the same matrix

Rotation is a deployable workflow, not a dashboard click. Create the replacement, overlap old and new briefly, confirm live traffic from every consumer returns success on the new key, then revoke the old one. The cases teams skip are all negative: an instance holding a stale secret, a delayed worker, a cached MCP process, a bulk job that started before rotation, a webhook retry after revocation. Any protected response after the cutoff is a critical failure.

Because every key in an account draws from one shared credit balance, a bulk job on one key can consume capacity another consumer needed, which is why per-key usage visibility belongs in the rotation plan. The RichAPI developer documentation covers the endpoint paths, bulk processing and webhook options the matrix has to exercise.

A green deploy proves the code shipped. It doesn't prove rotation finished. That evidence comes from provider-side usage records or a live dependency call on the new key.

Run the Key Test on Your Own Account Today

The shortest path from reading to evidence takes five moves.

  1. Sign up at app.richapi.ai. New accounts get 100 free credits with no card, enough to run the matrix more than once.
  2. Copy the key from the dashboard and put it in an environment variable.
  3. Send the Find Personal Email request from the first section and read the status against the table.
  4. Fix what the code tells you. A 401 or a 403 is a header or plan problem with a known remedy, so apply it and rerun.
  5. Extend to the full matrix. Add the negative cases and rotation checks, then use the same key in your REST calls or your MCP client. The MCP server at mcp.richapi.ai/mcp draws on the same key and the same balance when you call it from Claude or Cursor.

A key that passes on day one, in a header, with a clean 401 behind it, is the cheapest evidence you'll collect all quarter.

RichAPI puts 65+ GTM data endpoints behind one key, over REST and through an MCP server, so the single request you tested here is the same call your automations and agents will send in production. Credits are fixed per endpoint and misses on email and phone cost nothing, which makes a full test matrix cheap to run against real data. Start at RichAPI with 100 free credits and take that key through the checklist before you ship anything on top of it.

More from the blog