Search guides

Fix API key that does not work

We'll get your API key working—verify the key, format, and permissions, or rotate it if needed.

Troubleshooting · Security basics
5–15 min
What you'll need
  • API key from the provider
  • API documentation (for header/parameter format)
Step 1 of 10

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Verify the key, format, and permissions, or rotate the key if needed.

Verify the key

Copy the key again from the dashboard. Check for extra spaces, truncation, or wrong characters.

Good: Key is correct and complete.
Bad: Key was wrong—fix and retry.

Check format

Use the correct header or parameter per API docs (e.g. Authorization: Bearer <key> or X-API-Key: <key>).

Good: Format matches the API docs.
Bad: Wrong format—fix and retry.

Verify permissions and scopes

Goal: Confirm the key has the right scopes for the endpoint you are calling.

In the provider dashboard, check the key scopes or permissions. Add the required scope (e.g. read, write, admin) if it is missing. Retry the request.

Good: Permissions match and the request succeeds.
Bad: Still fails—check if the key is expired or revoked, or rotate it.

Check if the key is expired or revoked

Goal: Confirm the key is active and not expired or revoked.

In the dashboard, check the key status and expiration. If the key is expired or revoked, create a new one and update your app or config.

Good: Key is active or you have created a new one.
Bad: Key is expired or revoked—rotate it.

Check IP or domain restrictions

Goal: Confirm your request comes from an allowed IP or domain.

Some providers restrict keys by IP or domain. If your key has restrictions, verify your request comes from an allowed source. Add your IP or domain in the dashboard if needed.

Good: Restriction matches your request source.
Bad: Still fails—rotate the key or contact support.

Test with a minimal request

Goal: Isolate whether the issue is the key or your app code.

Run a test with curl or Postman using a simple request from the API docs. This isolates whether the key and format work.

Good: Minimal request succeeds—the issue may be in your app code.
Bad: Minimal request fails—key, format, or permissions are still wrong.

Rotate the key

If the key was exposed or revoked, create a new one from the dashboard and update your app or config.

Good: New key works.
Bad: Still fails—contact support.

When to get help

Contact the API provider if the key is valid, correctly formatted, and has the right permissions—but the API still rejects it. Provide the error message and endpoint.

Verification

  • The API accepts your requests.
  • No “invalid key”, “401”, or “403” errors.
  • The key has the expected permissions for the endpoint.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Verify key Copy the key again; check for spaces, truncation, wrong character.
  2. Check format Use the correct header or parameter per API docs.
  3. Check permissions Verify the key has the right scopes for the endpoint.
  4. Rotate key Create a new key if it was exposed or revoked.
  5. Contact support Provide error message, endpoint, and steps tried.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • API provider and endpoint
  • Error message (e.g. "invalid key", "401")
  • Whether the key was copied correctly
  • Header or parameter format used

Does the API reject your key?

Check the error message. "Invalid key", "401", or "403" often mean key, format, or permission issues.

Check the error message. Good: "invalid key", "401", "403" — follow this guide. Bad: different error — check the specific message.

Yes No

You can change your answer later.

Is the key copied correctly?

No extra spaces, truncation, or wrong character.

Copy the key again from the dashboard. Check for spaces, truncation. Good: key is correct. Bad: key was wrong — fix and retry.

Yes No

You can change your answer later.

Copy the key again and retry

Copy from dashboard. Check for spaces, truncation. Update your app. Retry.

Copy the key again from the dashboard. Check for extra spaces, truncation. Update your app or config. Retry the request. Good: request succeeds. Bad: still fails — check format.

Yes No

You can change your answer later.

Is the key sent in the correct format?

Check API docs for header or parameter (e.g. Authorization, X-API-Key).

Use the correct header or parameter per API docs. Good: format correct. Bad: wrong format — fix and retry.

Yes No

You can change your answer later.

Fix the format and retry

Use the correct header or parameter per API docs. Retry.

Check API docs for the exact header (e.g. Authorization: Bearer <key> or X-API-Key: <key>). Fix your request. Retry. Good: request succeeds. Bad: still fails — check permissions.

Yes No

You can change your answer later.

Does the key have the right permissions?

Check scopes in the dashboard. Add required scope if needed.

Check key scopes. Add required scope. Good: permissions match. Bad: still fails — rotate key or contact support.

Yes No

You can change your answer later.

Add required scope and retry

Add the required scope in the dashboard. Retry.

In the provider dashboard, add the required scope (e.g. read, write, admin) for the endpoint. Update your request. Retry. Good: request succeeds. Bad: still fails — rotate key or contact support.

Yes No

You can change your answer later.

Did rotating the key help?

Create a new key if the old one was exposed or revoked.

Create a new key. Update your app. Good: new key works. Bad: still fails — contact support.

Yes No

You can change your answer later.

API key working?

API key is working. No further action needed.

Done

Contact support

Contact the API provider with the error message, endpoint, and steps you have tried.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why would an API key not work?
Common causes: typo or truncation when copying, wrong permissions or scopes, expired or revoked key, incorrect header or parameter name, or IP/domain restrictions. Check the key and how it is sent first.
Should I rotate my API key if it was exposed?
Yes. If the key was committed to a repo, logged, or shared, revoke it and create a new one. Update your app or config with the new key. Do not reuse exposed keys.
What if the API says "invalid key" but I copied it correctly?
Check permissions—the key may not have access to the endpoint you are calling. Verify the header name (e.g. Authorization: Bearer <key> or X-API-Key: <key>). If both are correct, the key may be revoked—create a new one.

Rate this guide

Was this helpful?

Continue to