> 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/security/api-key-security.md).

# API-Key Security

API keys are secrets. Store them in server-side secret stores or environment variables. Do not place them in browser code, git, URLs, logs, screenshots, or tickets.

Use a dedicated least-privilege user for automation because keys inherit user permissions and have no per-key scopes.

## Why API Keys Need Care

An API key authenticates as its owning user. If the owner has SuperAdmin, the key has SuperAdmin-level REST access. If the owner has `topology_write`, the key can change inventory and topology. NetMap does not implement per-key scopes, so the user account is the permission boundary.

## Safe Storage Patterns

Use:

* CI/CD secret variables;
* server environment variables;
* a secret manager;
* root-readable deployment files with restricted permissions.

Avoid:

* source control;
* frontend JavaScript;
* shell history;
* query strings;
* screenshots;
* shared notes;
* logs.

## Recommended Automation Account

Create a dedicated user for each major integration. Assign only the required permissions:

| Automation                       | Suggested permissions              |
| -------------------------------- | ---------------------------------- |
| inventory export job             | `inventory_export`                 |
| syslog export job                | `security_view`, `firewall_export` |
| IPAM sync                        | `ipam_write`                       |
| discovery job                    | `topology_write`                   |
| monitoring service check manager | `monitoring_write`                 |

## Rotation

Rotate keys by creating a new key, updating automation, verifying success, and revoking the old key. There is no in-place rotation endpoint.

## Compromise Response

1. Revoke the key.
2. Review audit logs and affected user permissions.
3. Rotate related secrets if the exposure included scripts or environment files.
4. Create a replacement key only after the source of exposure is fixed.

## Related Pages

* [API Keys](/api/api-keys.md)
* [Rotating API Keys](/api/rotating-api-keys.md)
* [Revoking API Keys](/api/revoking-api-keys.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/security/api-key-security.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.