API keys and scopes

An API key lets a script or an AI agent call the API or the MCP endpoint without a person signing in. Each key has a name, a set of scopes, an optional list of profiles and an expiry date.

Create a key

1. Open the web app at vulngraph.igentify.in and go to API Keys.
2. Choose Create API key, give it a name (up to 80 characters), pick the scopes, and optionally limit it to some profiles. Pick an expiry: 30, 60, 90 (default), 180 or 365 days.
3. Copy the key from the Key created — copy it now screen. It is shown only once. The same screen shows how to use the key with MCP.

Keys look like vg_live_<10-character id>_<40-character secret>. The app lists a key by its prefix (vg_live_ plus the first 4 id characters) and its last 4 characters.

Use a key

Send it as a bearer token:

curl -s -H "Authorization: Bearer $VULNGRAPH_API_KEY" \
  https://api.vulngraph.igentify.in/v1/runs/latest

Keep the key out of code and chat. Store it in a file only you can read (mode 600, for example ~/.vulngraph/<name>.key) or in an environment variable, and read it inside the command.

Scopes

Give each key only the scopes it needs. Read scopes cannot change anything.

Scope	Kind	Risk	Allows
runs:read	read	low	List runs, read one run, the events feed
findings:read	read	low	Portfolio answers (summary, start here, services, advisories, packages, next steps, changes, trend)
profiles:read	read	low	List profiles and read one profile
plans:read	read	medium	The remediation plan, its steps and the recorded decisions and status
sketches:read	read	medium	PR sketches
logs:read	read	medium	Scan logs
artifacts:download	read	medium	Download run files (report, brief, plan, sketch)
decisions:write	write	high	Record a choice on a Decide step
step-status:write	write	medium	Record that a step is in progress, has a PR opened or merged, or was skipped
runs:create	write	high	Start a new scan

A call outside the key's scopes answers 403 {"error": "missing scope <scope>"}. The exact scope of every endpoint is in the API reference.

Profile limits. A key limited to some profiles sees only their runs, plans and portfolio answers. Other profiles answer 404, and starting a run for one answers 403.

What keys can never do. Keys cannot create, change or revoke keys (403). They cannot clear a decision or a status, or overwrite a decision a person recorded (409).

Expiry, revocation and activity

• Expiry. An expired key answers 401. Keys are not renewed; create a new one.
• Revocation. Revoke a key on its page in the app. It stops working within about 30 seconds.
• Lost key. It cannot be shown again. Revoke it and create a new one.
• Activity. Every request with a key, including denied ones, is recorded with method, path, status and IP for 90 days, with daily counters for the last 30 days. MCP calls show the tool name. Create, rename and revoke events are kept for good. Open a key in the app to see its activity.

Key management API (signed-in users only)

These routes accept a signed-in web-app session only; an API key gets 403 {"error":"API keys cannot manage API keys"}.

Method and path	What it does
GET /keys	Up to 200 keys, newest first, plus the scope catalog, expiry choices and limits
POST /keys	Create: {"name", "scopes": [...], "expiresInDays"?: 1-365, "profiles"?: [...]} → 201 {"token": "vg_live_…", "key": {...}}. The token appears in this answer only
GET /keys/{keyId}	One key, daily counters for 30 days (requests, writes, denied) and the last 50 lifecycle events
GET /keys/{keyId}/activity?filter=all|writes|denied&cursor=	Request log, 50 per page
POST /keys/{keyId}	Rename: {"name"} (1 to 80 characters)
POST /keys/{keyId}/revoke	Revoke (safe to repeat)

A key record has keyId, name, prefix, last4, scopes, profiles, createdAt, createdBy, expiresAt, revokedAt, revokedBy, lastUsedAt, lastUsedIp and status (active, expired or revoked).