Authentication

OpenProspect external API requests use API keys. Internal frontend sessions use Hanko, but Hanko tokens are not part of the external developer integration.

Header Format

Send the API key as a bearer token on every request.

Authorization: Bearer lnc_live_your_api_key_here

Use the production base URL unless your OpenProspect contact gives you a different environment URL.

https://api.openprospect.io

Validate a Key

GET /api/v1/auth/validate

Requires any valid API key. The endpoint confirms that the key is active and returns the scopes assigned to it.

cURLPythonJavaScriptTypeScriptC#

curl -sS https://api.openprospect.io/api/v1/auth/validate \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}"

import os

import httpx

api_key = os.environ["OPENPROSPECT_API_KEY"]

response = httpx.get(
    "https://api.openprospect.io/api/v1/auth/validate",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30.0,
)
response.raise_for_status()
print(response.json())

const apiKey = process.env.OPENPROSPECT_API_KEY;

const response = await fetch("https://api.openprospect.io/api/v1/auth/validate", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  throw new Error(`OpenProspect auth failed: ${response.status}`);
}

console.log(await response.json());

interface ValidationResponse {
  valid: boolean;
  scopes: string[];
}

const apiKey = process.env.OPENPROSPECT_API_KEY;

const response = await fetch("https://api.openprospect.io/api/v1/auth/validate", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  throw new Error(`OpenProspect auth failed: ${response.status}`);
}

const result = (await response.json()) as ValidationResponse;
console.log(result.scopes);

using System.Net.Http.Headers;

var apiKey = Environment.GetEnvironmentVariable("OPENPROSPECT_API_KEY")
    ?? throw new InvalidOperationException("OPENPROSPECT_API_KEY is not set.");

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

var response = await client.GetAsync("https://api.openprospect.io/api/v1/auth/validate");
response.EnsureSuccessStatusCode();

Console.WriteLine(await response.Content.ReadAsStringAsync());

Expected response:

{
  "valid": true,
  "scopes": ["orders:read", "orders:write", "companies:read", "prospects:read"]
}

Scopes

API keys are scoped. Request only the scopes your integration needs.

Scope	Enables
orders:write	Create search profile requests and briefing orders
orders:read	List orders, read order status, and fetch order results
companies:read	Required together with prospects:read for delivered CRM sync
prospects:read	Required together with companies:read for delivered CRM sync
delivery:read	Read website markdown for a delivered company
prospect_searches:read	List prospect searches available to the key owner
blacklists:read	Read blacklists, entries, and assignments
blacklists:write	Create, update, delete, and assign blacklists

Presets

Preset	Scopes
Orders	orders:read, orders:write, companies:read, prospects:read, delivery:read, prospect_searches:read, blacklists:read, blacklists:write
Read Only	orders:read, companies:read, prospects:read, delivery:read, prospect_searches:read, blacklists:read
Full Access	All eight remaining scopes
Custom	Any non-empty subset of the eight remaining scopes

Common Authentication Errors

Status	Code	Cause	Resolution
401	UNAUTHORIZED	Missing, malformed, expired, or revoked API key	Send Authorization: Bearer lnc_live_... with an active key
403	AUTHORIZATION_ERROR	The key is valid but lacks a required remaining-route scope	Add the listed remaining-route scope or use a different key
403	API_KEY_ROUTE_FORBIDDEN	The key is valid but the URL is a closed pipeline or source-data route	Use GET /api/v1/deliveries/{prospect_search_id}/companies and GET /api/v1/deliveries/{prospect_search_id}/companies/{company_id}/website-markdown. Adding scopes does not unlock those closed routes

See Error Handling for error response formats and retry behavior.