Authentication

The Precursor Intelligence API uses bearer tokens for every request. There are no cookies, no session state, no OAuth dance: just one header.

Get an API key

API keys are managed from your Precursor Intelligence dashboard.

1. Sign in at precursorintelligence.com.
2. Open Settings → API Keys.
3. Click Create key and give it a name for your reference (e.g. prod-backend, staging-cron).
4. Optionally add an IP allowlist: up to 20 individual IPv4 or IPv6 addresses permitted to use this key. Enter one address per entry; CIDR ranges and network masks are not accepted.
5. Optionally set an expiry date. After that time the key stops working automatically. Leave it blank for a key that never expires.
6. Click Generate.

Keys are organisation-owned. All members of an organisation share one credit pool, and one key can carry scopes for both the REST API and the MCP server.

Scopes

Each key carries one or more scopes that gate which endpoints it can call:

api:org is a separate grant, not an upgrade — an api:read key calling a /my/* endpoint receives the same uniform 401 unauthorized as any other auth failure, so scope assignment is never leaked. The /my/* endpoints resolve the organisation from the key itself and inject it server-side; it can never be supplied or overridden in the request, so a key only ever reads its own organisation's data.

Scopes are chosen when the key is created under Settings → API Keys.

Make an authenticated request

Pass the full token in the standard Authorization header:

curl https://api.precursorintelligence.com/functions/v1/cve/CVE-2024-3094 \
  -H "Authorization: Bearer $PRECURSOR_API_KEY"

Language examples

const res = await fetch(
  'https://api.precursorintelligence.com/functions/v1/cve/CVE-2024-3094',
  {
    headers: {
      Authorization: `Bearer ${process.env.PRECURSOR_API_KEY}`,
    },
  }
)
const { data, meta } = await res.json()

import os, requests
 
r = requests.get(
    "https://api.precursorintelligence.com/functions/v1/cve/CVE-2024-3094",
    headers={"Authorization": f"Bearer {os.environ['PRECURSOR_API_KEY']}"},
    timeout=10,
)
r.raise_for_status()
payload = r.json()

req, _ := http.NewRequest("GET",
    "https://api.precursorintelligence.com/functions/v1/cve/CVE-2024-3094", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("PRECURSOR_API_KEY"))
resp, err := http.DefaultClient.Do(req)

IP allowlists

When a key has an allowlist configured, the API checks the verified source IP on every request. Mismatches return 401 unauthorized with no additional detail. An allowlist accepts up to 20 individual IPv4 or IPv6 addresses, one per entry. CIDR ranges and network masks are not accepted.

Key expiry

When you create a key you can set an optional expiry date. After that timestamp the key stops working automatically and calls return 401 unauthorized. A key created without an expiry date never expires. The expiry is fixed at creation, so to extend a key's life, rotate to a new one.

Rotate and revoke keys

From Settings → API Keys, select a key and click Revoke. The key is disabled immediately and all subsequent calls return 401 unauthorized. There is no grace period.

To rotate a key with zero downtime, create the replacement first, roll it out to your clients, then revoke the old key once traffic has shifted.