# auth.md

You are an agent. This document is the self-contained source of truth for how to register and use a credential (an API key) to authenticate to the Vulners MCP server (mcp.vulners.com) and the Vulners vulnerability intelligence API behind it. It is written for AI agents and other automated clients.

## This server holds no privileged API key of its own

This server never has a privileged Vulners API key of its own to spend on your behalf, and it never issues, stores, or shares your key. A caller-supplied key that Vulners itself rejects (expired, revoked, wrong scope) is never silently retried on any other key -- you get a sanitized error back, not a masked failure.

## Two ways to call it

- **Bring your own key (full limits).** Send your personal Vulners API key in the `X-Api-Key` HTTP request header on MCP tool calls (`tools/call`). It is forwarded to the Vulners API for that request only: full limits, no result-size clamp, no app-level rate limit.
- **Anonymous tier (reduced limits).** Omit the `X-Api-Key` header entirely and the call still goes through, on this deployment's own dedicated, low-privilege key -- when one is configured. Result-size arguments are clamped to 10, and anonymous calls share a modest, app-level rate limit protecting that shared key's quota. If the anonymous-tier key's own quota or rate limit is exhausted upstream, you get a structured error telling you to send your own key for full limits. If this deployment has no anonymous tier configured at all, a keyless call fails immediately with a guidance error instead of being forwarded.
- **Discovery is always open**: `initialize` and `tools/list` work without a key either way, so an agent can inspect what this server offers before deciding whether it needs its own key.

## Getting or rotating a key (humans only)

Sign in at https://vulners.com/userinfo in a regular web browser to create, view, or rotate your API key. That page is protected by an interactive challenge -- an agent or automated client fetching it directly gets a challenge page back instead of a key, by design. A human has to complete this step.

Key scopes (`api`, `scan`, `report`) and IP allowlists are also configured there.

## Self-hosted / stdio mode

Running this server yourself over stdio (e.g. from Claude Desktop)? Set the `VULNERS_API_KEY` environment variable to your own key. In stdio mode the server uses it for every tool call, since there is no per-request HTTP header available -- the anonymous tier is an HTTP-transport concept only and does not apply here.

## Supported registration methods

- `user_delegated` — a human operator registers an account and provisions an
  API key for the agent (the only method today).
- Anonymous provisioning and identity assertions (ID-JAG, verified email) are
  not supported.

## Step 1 — Register and provision a credential

Registration is interactive (human-in-the-loop):

1. Create an account: https://vulners.com/signup
2. Open the API keys section of the personal area: https://vulners.com/userinfo
3. Generate an API key (credential type: `api_key`). Optional per-key scopes
   (`api`, `scan`, `report`) and an optional IP allowlist are configured there.

Both URLs above return an interactive Cloudflare browser challenge to
non-browser clients — an agent fetching them directly gets a 403. They must
be opened in a regular browser by the human operator.

There is no unauthenticated provisioning endpoint; ask your user to complete
this step and hand you the key.

## Step 2 — Use the credential

Send the API key in the `X-Api-Key` request header on every call. Search is a
POST endpoint that takes its parameters as a JSON body, not query string:

```http
POST /api/v3/search/lucene HTTP/1.1
Host: vulners.com
X-Api-Key: <your-api-key>
Content-Type: application/json

{"query": "type:cve", "size": 10}
```

Machine-readable API description: https://vulners.com/api/openapi.json
(security scheme: `apiKey` in header `X-Api-Key`) — this OpenAPI spec covers
the `/api/v4/audit/*` and STIX endpoints only; it does not describe search.
Search and the rest of the API are documented at
https://docs.vulners.com/docs/api/ and reachable through the Vulners MCP
server. Requests carrying a valid `X-Api-Key` bypass interactive browser
checks.

## Step 3 — Rotation and revocation

Keys are listed, rotated and revoked at https://vulners.com/userinfo.
If a previously working key starts returning 401/403, it was revoked or its
IP allowlist no longer matches — obtain a new key via Step 1; do not retry
with the stale credential.

## Full registration walk-through

For the complete, non-agent-specific walkthrough of Vulners account creation and key management, see https://vulners.com/auth.md.

## Machine-readable descriptors

- MCP server card: https://mcp.vulners.com/.well-known/mcp/server-card.json