> For the complete documentation index, see [llms.txt](https://docs.netmap.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.netmap.dev/troubleshooting/api-key-problems.md).

# API-Key Problems

API-key failures usually separate into authentication failures (`401`), authorization failures (`403`), rate limits (`429`), or reverse-proxy header problems.

| Symptom                                    | Cause                        | Fix                                                 |
| ------------------------------------------ | ---------------------------- | --------------------------------------------------- |
| `401 Authentication required`              | Missing `X-API-Key`          | Add the header.                                     |
| `401 Invalid, expired, or revoked API key` | Bad, expired, or revoked key | Generate a replacement.                             |
| `401 Invalid or inactive user`             | Owner disabled/deleted       | Reactivate owner or create another automation user. |
| `403`                                      | Role lacks permission        | Grant permission or use a different owner.          |
| `429 API key rate limit exceeded`          | Per-key rate limit           | Back off or tune limits.                            |
| `429 Too many failed API key attempts`     | Invalid-key lockout          | Stop bad requests and wait.                         |
| Header works direct but not through proxy  | Proxy strips header          | Preserve `X-API-Key`.                               |

## Verify The Header

```bash
API_URL="https://netmap.example.com"
API_KEY="<api-key>"

curl --fail-with-body \
  --url "${API_URL}/api/v1/auth/me" \
  --header "X-API-Key: ${API_KEY}" \
  --header "Accept: application/json"
```

Do not use:

```
Authorization: Bearer <api-key>
```

API keys are not bearer tokens.

## Check Key State

In the UI:

1. Sign in as the key owner.
2. Open Profile.
3. Review API key name, prefix, expiry, revoked state, last-used time, and last-used IP.

SuperAdmins can review all keys from Admin.

## Check Permissions

If `/api/v1/auth/me` works but a feature endpoint returns `403`, the key is valid and the owner lacks permission. Update the owner role or use a different automation user.

## Related Pages

* [API Keys](/api/api-keys.md)
* [API Authentication](/api/authentication.md)
* [API-Key Permissions](/api/api-key-permissions.md)
* [Reverse Proxy Problems](/troubleshooting/reverse-proxy-problems.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.netmap.dev/troubleshooting/api-key-problems.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.