Authentication

Every /v1/ operation accepts either of these headers. They carry the same API key. The OpenAPI security schemes are apiKey (X-API-Key) and apiKeyBearer (Authorization: Bearer). This is not a JWT. Do not send an app session cookie to the machine API. The app session cookies are __Host-vln_at and __Host-vln_rt. See Security and compliance.

Authorization: Bearer vln_live_...

X-API-Key: vln_live_...

Live keys use the prefix vln_live_. Test keys use vln_test_. Create the key in the app and store it as VULNIFY_API_KEY. See API keys.

The Node.js and Python SDKs send Authorization: Bearer. X-API-Key is equivalent when you call the API yourself.

A missing, invalid, revoked, or expired key returns HTTP 401. A call with no valid key returns:

{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}

The SDKs read message and raise. failMode / fail_mode does not apply to a 401. See Errors.

HTTP 403 means the key is bound to another agent, or the caller IP is not in the key allowlist. POST /v1/policies/apply also returns 403 when the key is not an org-wide LIVE key. The body is {"error":"forbidden","message":"policies:apply requires an org-wide LIVE key"}. See Policies.

Idempotency-Key

POST /v1/events, POST /v1/gateway/http, and POST /v1/gateway/mcp accept an optional header:

Idempotency-Key: 3c1b0e2a-7c4d-4e1a-9f0a-6b2d8e4a1c55

Retries with the same key, for the same organization and endpoint, within 24 hours, return the stored decision instead of deciding again. The replay always includes finalDecision, derived from the stored decision and the current review, including a replay of a response stored before that field existed. When that happens the response includes Idempotent-Replay: true.

The SDKs send a new UUID on each check() unless you pass idempotencyKey / idempotency_key. Retries of that check reuse the same key, so a retry does not create a second event.

GET /v1/events/{id} does not use this header.

Response headers

Successful POST responses can include X-Request-Id, x-api-version (contract v1), x-vulnify-version (API build SemVer), and Idempotent-Replay. GET /v1/events/{id} includes the same headers except Idempotent-Replay. The per-operation tables list the descriptions from the spec.

HTTP 429 means the rate limit was exceeded. Some responses also include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset. Those headers are not part of the OpenAPI document, and the numbers differ by route, so this reference does not publish a fixed limit. Event quotas are a separate, soft limit on the organization. See Plans.