Docs/Developer Platform/API Access

Developer API Access & Key Management Guide

Enterprise 3-tier integration guide: interactive 5-minute quickstart, 6-stage visual lifecycle onboarding, least-privilege permission scopes, high-entropy credentials, and real-time signed event streaming.

Least-Privilege ScopedHigh-Entropy Hashed KeysSigned Webhook & SSE DeliveryOpenAPI 3.1.0 Verified

Search API endpoints, setup steps, scopes, or ask AI...

Ask AI⌘K

Suggested:

Architecture & Zero-Trust Perimeter

The KeyPriv Developer Platform provides a secure, least-privilege REST API and real-time event delivery stream designed for SIEM, SOAR, ITSM, and SOC automation pipelines. Developer Applications operate under an air-gapped, zero-trust security perimeter: credentials never access other organizations, and keys are cryptographically hashed using SHA-256 before storage.

Zero-Trust Isolation: All API requests are cryptographically verified against your organization boundary. Unauthenticated or mis-scoped requests are rejected at the edge gateway before touching application services.

Tier 1: 5-Minute Quickstart & Interactive Playground

Test live requests instantly against either the Production or Sandbox environment using the interactive code runner below. Toggle environments to see prefix and host updates in real-time.

Interactive Request Runner: GET /v1/intelligence/findings

curl -X GET "https://app.keypriv.com/v1/intelligence/findings?limit=50&severity=critical" \
  -H "X-API-Key: kpv_prd_YOUR_KEY_HERE" \
  -H "Accept: application/json"

Response200OK

{
  "total": 124,
  "limit": 50,
  "has_more": true,
  "next_cursor": "eyJpZCI6ImV4YW1wbGUtY3Vyc29yIn0=",
  "items": [
    {
      "id": "fnd_sample_01",
      "threat_type": "credential_exposure",
      "severity": "critical",
      "compromised_domain": "example.com",
      "source_leak": "Dark Web Intelligence Dump #102",
      "discovered_at": "2026-10-12T19:45:00Z"
    },
    {
      "id": "fnd_sample_02",
      "threat_type": "exposed_subdomain_takeover",
      "severity": "high",
      "compromised_domain": "vpn-staging.example.com",
      "source_leak": "Dark Web Intelligence Dump #102",
      "discovered_at": "2026-10-12T18:20:12Z"
    }
  ]
}

Tier 2: Visual 6-Stage Walkthrough & Lifecycle Onboarding

Developer Applications follow a structured security progression. A new application is securely onboarded across 6 stages to guarantee that credentials, least-privilege scopes, and delivery endpoints are fully verified before promoting the integration to active status:

Application Onboarding & Lifecycle Progression

— 6-stage security walkthrough

Stage 1 of 6

Stage 1: App Configuration→Next: Permission Scopes

Identity & Target Environment

Application Profile Initialized

Registers the application identity, environment plane (Production or Sandbox), and consumer architecture (SIEM, SOAR, ITSM, or custom backend).

Verification Criteria

Name length 3–80 characters
Unique name within organization
Target environment selected

Required Parameters

app_name (String)
app_type (Enum)
env (production | sandbox)

Navigate to the developer settings panel to begin onboarding your application.

In the platform sidebar, expand Settings and click API Access.
If this is your first application, the system displays the Developer App Lifecycle Rail in draft mode.
Click Start developer app (or New developer app) to initialize your workspace draft.

API Access Overview & Lifecycle Rail — Figure 0.1: Developer App Lifecycle Rail and settings overview

Start of onboarding walkthrough

Registers the identity, target environment, and integration type for your developer app.

Step 1: App Name and Configuration — Figure 1.1: Setting App Name, Integration Type, and Isolation Plane

Step 1 Configuration Schema (Tri-View)

3 fields

	Parameter	Type	Requirement	Description & Rules
	app_name	string	Required	Descriptive human-readable identifier for your integration. Rule: 3–80 characters, alphanumeric, spaces, hyphens

Parameter

Type

Requirement

Description & Rules

app_name

string

Required

Descriptive human-readable identifier for your integration.

Rule: 3–80 characters, alphanumeric, spaces, hyphens

	Parameter	Type	Requirement	Description & Rules
	app_type	enum	Required	Architecture type of consumer connecting to KeyPriv. Rule: 'SIEM / SOAR / ITSM' \| 'Custom backend' \| 'Partner app' \| 'CLI / Script' \| 'Other'
	env	enum	Required	Target security and network isolation plane. Rule: 'production' \| 'sandbox'

Parameter

Type

Requirement

Description & Rules

app_type

enum

Required

Architecture type of consumer connecting to KeyPriv.

Rule: 'SIEM / SOAR / ITSM' | 'Custom backend' | 'Partner app' | 'CLI / Script' | 'Other'

env

enum

Required

Target security and network isolation plane.

Rule: 'production' | 'sandbox'

Pre-Flight Check: KeyPriv verifies that the application name is unique within your organization and between 3 and 80 characters. Click Continue to advance to Step 2.

Tier 3: Security Hardening & Technical Reference

Production hardening standards for enterprise automation: cryptographic authentication, granular scope isolation, HMAC webhook verification, rate limiting, and standard HTTP error codes.

Authentication

Authenticate all HTTP REST and SSE requests by passing your API key in the X-API-Key request header.

Required Authentication Headers (Tri-View)

2 fields

	Parameter	Type	Requirement	Description & Rules
	X-API-Key	string	Required	High-entropy secret key generated in Step 3. Rule: Format: kpv_prd_... (production) or kpv_sbx_... (sandbox)

Parameter

Type

Requirement

Description & Rules

X-API-Key

string

Required

High-entropy secret key generated in Step 3.

Rule: Format: kpv_prd_... (production) or kpv_sbx_... (sandbox)

	Parameter	Type	Requirement	Description & Rules
	Accept	string	Required	Content negotiation header defining the response representation.

GET/v1/intelligence/findings

Retrieves paginated intelligence findings, compromised credentials, and threat signals correlated to your organization assets.

Query Parameters (Tri-View)

4 fields

	Parameter	Type	Requirement	Description & Rules
	limit	integer	Optional	Maximum findings to retrieve per page. Rule: 1–500 records
	cursor	string	Optional	Opaque pagination cursor for forward traversal. Rule: Base64 encoded pagination token

Parameter

Type

Requirement

Description & Rules

limit

integer

Optional

Maximum findings to retrieve per page.

Rule: 1–500 records

cursor

string

Optional

Opaque pagination cursor for forward traversal.

Rule: Base64 encoded pagination token

	Parameter	Type	Requirement	Description & Rules
	severity	enum	Optional	Filter findings by severity level. Rule: 'critical' \| 'high' \| 'medium' \| 'low'
	source_type	string	Optional	Filter findings by dark web or exposure source type. Rule: 'darkweb' \| 'paste' \| 'forum' \| 'email_leak' \| 'network_scanner'

Parameter

Type

Requirement

Description & Rules

severity

enum

Optional

Filter findings by severity level.

Rule: 'critical' | 'high' | 'medium' | 'low'

source_type

string

Optional

Filter findings by dark web or exposure source type.

Rule: 'darkweb' | 'paste' | 'forum' | 'email_leak' | 'network_scanner'

SSE/v1/stream/events

Opens a persistent Server-Sent Events (SSE) connection that pushes findings and correlation alerts to your pipeline in real-time.

Real-Time Event Stream Consumption

curl -N -H "X-API-Key: kpv_prd_YOUR_KEY_HERE" \
  -H "Accept: text/event-stream" \
  "https://app.keypriv.com/v1/stream/events?app_id=YOUR_APP_ID"

Webhook Event Delivery Schema

When configured for outbound webhooks, KeyPriv sends strongly typed event notifications to your HTTPS endpoint. Every event follows this standardized schema:

Webhook Event Delivery Schema (Tri-View)

6 fields

Parameter	Type	Requirement	Description & Rules
event_id	string	Required	Cryptographically unique UUIDv4 identifying the delivery event. Rule: UUIDv4 format
event_type	enum	Required	Classification of threat or system intelligence notification. Rule: 'finding.created' \| 'finding.updated' \| 'finding.remediated' \| 'key.rotated'
timestamp	string	Required	ISO 8601 UTC timestamp when the event was emitted by the platform. Rule: RFC 3339 / ISO 8601 format
correlation_id	string	Required	Traceability identifier correlating this delivery to source threat intelligence. Rule: UUIDv4 format
attempt	integer	Required	Delivery attempt sequence count. Automatically advances up to 5 during retries. Rule: 1–5

	Parameter	Type	Requirement	Description & Rules
	data+5 nested	object	Required	Structured event payload containing affected asset domains, severity metrics, and incident details.

Scope Permission Matrix

Scope Permission Specification (Tri-View)

4 fields

	Parameter	Type	Requirement	Description & Rules
	findings:read	scope	Optional	Query active and archived breach intelligence findings, compromised employee credentials, and exposure signals. Rule: Read-Only privilege level
	threats:read	scope	Optional	Access global dark web intelligence feeds, threat actor profiles, and IOC feeds. Rule: Read-Only privilege level

Parameter

Type

Requirement

Description & Rules

findings:read

scope

Optional

Query active and archived breach intelligence findings, compromised employee credentials, and exposure signals.

Rule: Read-Only privilege level

threats:read

scope

Optional

Access global dark web intelligence feeds, threat actor profiles, and IOC feeds.

Rule: Read-Only privilege level

	Parameter	Type	Requirement	Description & Rules
	events:stream	scope	Optional	Subscribe to real-time Server-Sent Events (SSE) notification streams for automated SOAR ingestion. Rule: Streaming privilege level
	remediation:write	scope	Optional	Trigger automated asset quarantine, DSAR takedown workflows, and case status transitions. Rule: Write privilege level

Parameter

Type

Requirement

Description & Rules

events:stream

scope

Optional

Subscribe to real-time Server-Sent Events (SSE) notification streams for automated SOAR ingestion.

Rule: Streaming privilege level

remediation:write

scope

Optional

Trigger automated asset quarantine, DSAR takedown workflows, and case status transitions.

Rule: Write privilege level

HMAC Webhook Signatures

Every webhook delivery dispatches an X-KeyPriv-Signature header computed as sha256=HMAC-SHA256(secret, rawPayload). Always verify this signature in constant time before parsing JSON:

HMAC-SHA256 Constant-Time Signature Verification

import hmac, hashlib

def verify_webhook(raw_payload: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Rate Limits & Quotas

The API gateway enforces a token-bucket algorithm at the organization level:

Standard Quota

1,000

Requests per minute per key

SSE Connections

Concurrent event streams per app

DLQ Retry Window

72h

Dead-letter replay buffer

HTTP Error Codes & RFC 7807 Standard Error Schema

KeyPriv returns RFC 7807 Problem Details for HTTP APIs with machine-parseable error codes:

RFC 7807 Problem Details Schema (Tri-View)

6 fields

	Parameter	Type	Requirement	Description & Rules
	type	string	Required	URI reference identifying the specific RFC 7807 error problem type.

	Parameter	Type	Requirement	Description & Rules
	title	string	Required	Short, human-readable summary of the problem category. Rule: e.g. Invalid Request Payload
	status	integer	Required	HTTP status code corresponding to the error. Rule: 400 \| 401 \| 403 \| 429 \| 500

Parameter

Type

Requirement

Description & Rules

title

string

Required

Short, human-readable summary of the problem category.

Rule: e.g. Invalid Request Payload

status

integer

Required

HTTP status code corresponding to the error.

Rule: 400 | 401 | 403 | 429 | 500

Parameter	Type	Requirement	Description & Rules
detail	string	Required	Human-readable explanation specific to this error occurrence.
code	string	Required	Machine-parseable enterprise error code for automated SIEM handling. Rule: 'INVALID_PAYLOAD' \| 'MISSING_OR_INVALID_KEY' \| 'INSUFFICIENT_SCOPE' \| 'RATE_LIMIT_EXCEEDED'
timestamp	string	Required	ISO 8601 timestamp when the exception was recorded at the API gateway. Rule: ISO 8601 format

Parameter

Type

Requirement

Description & Rules

detail

string

Required

Human-readable explanation specific to this error occurrence.

code

string

Required

Machine-parseable enterprise error code for automated SIEM handling.

Rule: 'INVALID_PAYLOAD' | 'MISSING_OR_INVALID_KEY' | 'INSUFFICIENT_SCOPE' | 'RATE_LIMIT_EXCEEDED'

timestamp

string

Required

ISO 8601 timestamp when the exception was recorded at the API gateway.

Rule: ISO 8601 format

Enterprise HTTP Error Taxonomy & Status Catalog

4 fields

Parameter	Type	Requirement	Description & Rules
400 Bad Request	HTTP 400	Optional	Request payload or query parameter failed validation schema constraints. Rule: INVALID_PAYLOAD
401 Unauthorized	HTTP 401	Optional	X-API-Key header is missing or does not match active cryptographic hash. Rule: MISSING_OR_INVALID_KEY
403 Forbidden	HTTP 403	Optional	API key is active but lacks the required permission scope or client IP is not in CIDR allowlist. Rule: INSUFFICIENT_SCOPE

Parameter

Type

Requirement

Description & Rules

400 Bad Request

HTTP 400

Optional

Request payload or query parameter failed validation schema constraints.

Rule: INVALID_PAYLOAD

401 Unauthorized

HTTP 401

Optional

X-API-Key header is missing or does not match active cryptographic hash.

Rule: MISSING_OR_INVALID_KEY

403 Forbidden

HTTP 403

Optional

API key is active but lacks the required permission scope or client IP is not in CIDR allowlist.

Rule: INSUFFICIENT_SCOPE

	Parameter	Type	Requirement	Description & Rules
	429 Too Many Requests	HTTP 429	Optional	Organization request limit exceeded (1,000 req/min). Inspect Retry-After header. Rule: RATE_LIMIT_EXCEEDED

Parameter

Type

Requirement

Description & Rules

429 Too Many Requests

HTTP 429

Optional

Organization request limit exceeded (1,000 req/min). Inspect Retry-After header.

Rule: RATE_LIMIT_EXCEEDED

Developer API Access & Key Management Guide

Architecture & Zero-Trust Perimeter

Tier 1: 5-Minute Quickstart & Interactive Playground

Tier 2: Visual 6-Stage Walkthrough & Lifecycle Onboarding

Application Onboarding & Lifecycle Progression

Identity & Target Environment

Step 0: Open API Access Settings & Lifecycle Rail

Step 1: Developer App Configuration

Step 1 Configuration Schema (Tri-View)

Step 2: Permissions & Scopes Selection

Step 3: API Credential Generation

Step 4: Event Delivery & Stream Configuration

Step 5: Test & Live Verification

Step 6: Active Management & Key Rotation

Tier 3: Security Hardening & Technical Reference

Authentication

Required Authentication Headers (Tri-View)

Query Parameters (Tri-View)

Webhook Event Delivery Schema

Webhook Event Delivery Schema (Tri-View)

Scope Permission Matrix

Scope Permission Specification (Tri-View)

HMAC Webhook Signatures

Rate Limits & Quotas

HTTP Error Codes & RFC 7807 Standard Error Schema

RFC 7807 Problem Details Schema (Tri-View)

Enterprise HTTP Error Taxonomy & Status Catalog