Skip to content

Authentication

Authentication

The OpenProspect API uses API keys for authentication. All requests must include your API key in the Authorization header.

API Key Format

API keys follow this format:

Text Only
lnc_live_<random_string>
  • lnc - OpenProspect prefix
  • live - Environment (live for production, test for sandbox)
  • Random string - Cryptographically secure random identifier

Example:

Text Only
lnc_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Making Authenticated Requests

Include your API key in the Authorization header with the Bearer scheme:

HTTP
GET /api/v1/companies/?prospect_search_id=<uuid> HTTP/1.1
Host: api.openprospect.io
Authorization: Bearer lnc_live_your_api_key_here

cURL Example

Bash
curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  https://api.openprospect.io/api/v1/companies/?prospect_search_id=<uuid>

Python Example

Python
import requests

headers = {
    "Authorization": "Bearer lnc_live_your_api_key_here"
}

response = requests.get(
    "https://api.openprospect.io/api/v1/companies/",
    headers=headers,
    params={"prospect_search_id": "<uuid>"}
)

TypeScript Example

TypeScript
const headers = {
  "Authorization": "Bearer lnc_live_your_api_key_here"
};

const response = await fetch(
  "https://api.openprospect.io/api/v1/companies/?prospect_search_id=<uuid>",
  { headers }
);

API Key Scopes

Each API key has specific permissions (scopes) that control what endpoints it can access:

Scope Description Endpoints
companies:read Read access to company data GET /api/v1/companies/*
companies:write Write access to company data POST, PUT, DELETE /api/v1/companies/*

Current API Coverage

Currently, only companies:read scope is available. Additional scopes will be added as more endpoints are released.

Getting an API Key

To obtain an API key:

  1. Contact your OpenProspect account manager
  2. Specify required scopes (currently companies:read)
  3. Specify tier (Free, Pro, or Enterprise)
  4. Receive your API key via secure channel

Keep Your API Key Secret

  • Never commit API keys to version control
  • Don't share API keys in public channels
  • Rotate keys regularly (at least every 90 days)
  • Use environment variables to store keys

Security Best Practices

Store Keys Securely

Use environment variables:

Bash
# .env file (add to .gitignore)
OPENPROSPECT_API_KEY=lnc_live_your_api_key_here

Load in your application:

Python
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("OPENPROSPECT_API_KEY")
TypeScript
import * as dotenv from 'dotenv';

dotenv.config();
const apiKey = process.env.OPENPROSPECT_API_KEY;

Use HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected:

Text Only
✅ https://api.openprospect.io/api/v1/companies/
❌ http://api.openprospect.io/api/v1/companies/

Rotate Keys Regularly

Best practices:

  • Rotate keys every 90 days minimum
  • Rotate immediately if key is compromised
  • Use separate keys for development/staging/production
  • Implement key rotation in CI/CD pipelines

Monitor Key Usage

Track API key usage to detect anomalies:

  • Unusual request patterns
  • Requests from unexpected IP addresses
  • Spike in error rates
  • Access to unauthorized resources

Contact your account manager if you notice suspicious activity.

Error Responses

401 Unauthorized

Missing or invalid API key:

JSON
{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key"
}

Common causes:

  • API key not included in Authorization header
  • Invalid API key format
  • Expired or revoked API key
  • Missing Bearer prefix

403 Forbidden

Valid API key but insufficient permissions:

JSON
{
  "error": "FORBIDDEN",
  "message": "Insufficient scopes. Required: companies:read"
}

Common causes:

  • API key lacks required scope
  • Attempting to access resources outside your organization
  • API key tier doesn't support requested feature

Rate Limits

Rate limits are enforced per API key. See API Overview for details.

Testing Your API Key

Verify your API key works:

Bash
curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  https://api.openprospect.io/health

Expected response:

JSON
{
  "service": "OpenProspect API",
  "status": "healthy"
}

Revoking API Keys

To revoke an API key:

  1. Contact your account manager
  2. Provide the key ID or first/last 8 characters
  3. Key will be revoked within 5 minutes
  4. All subsequent requests with that key will return 401

Key Rotation Process

  1. Generate new API key
  2. Update applications to use new key
  3. Verify new key works in production
  4. Revoke old key
  5. Monitor for errors

FAQ

Can I use multiple API keys?

Yes, you can have multiple API keys per organization. This is useful for:

  • Separating environments (dev/staging/prod)
  • Different applications or services
  • Key rotation without downtime

What happens if my key is compromised?

Contact your account manager immediately to:

  1. Revoke the compromised key
  2. Generate a new key
  3. Review audit logs for suspicious activity

Can I regenerate the same API key?

No, each key is unique and cannot be regenerated. You must create a new key and revoke the old one.

Do API keys expire?

API keys don't have automatic expiration, but we recommend rotating them every 90 days as a security best practice.

Support

Questions about authentication?