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 enrichment and discovery orders
orders:read	List orders, read order status, and fetch order results
companies:read	Read company records, hiring activity, web technology data, and delivery sync data
prospects:read	Read prospect/contact records and delivery sync data
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
Enrichment Orders	orders:write, orders:read, companies:read, prospects:read
Discovery Orders	orders:write, orders:read, companies:read, prospects:read, blacklists:read, blacklists:write
CRM Sync	companies:read, prospects:read
Blacklist Management	blacklists:read, blacklists:write

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 scope	Add the required scope or use a different key

See Error Handling for error response formats and retry behavior.