Learn how to generate a PerfectParser API key and authenticate every request using the X-API-Key header.

All API requests to api.perfectparser.com must include a valid API key. PerfectParser uses a simple header-based authentication scheme — no OAuth flows, no token expiry.

Generate an API key

Sign in to your PerfectParser dashboard.
Click Integrations in the left sidebar.
Open the API Keys tab and click Generate Key.
Copy the key immediately — it is shown only once for security.

API keys are secret credentials. Never commit them to source control or expose them in client-side code. Store them as environment variables.

Using your API key

Include your key in the X-API-Key request header for every API call:

curl https://api.perfectparser.com/v1/extractions \
  -H "X-API-Key: pp_live_your_secret_key"

Header reference

Header	Required	Description
`X-API-Key`	✅ Yes	Your PerfectParser API key.
`Idempotency-Key`	Optional	On `POST /v1/extractions` only — prevents duplicate jobs on retries. See Start Extraction.

Rate limits

Rate limits apply per API key across all endpoints (not per-endpoint buckets).

Scope	Limit
All endpoints (global)	150 requests / minute
`POST /v1/extractions`	20 requests / minute (tighter cap — each call charges credits)

Every response includes rate-limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining before the limit is hit
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets

When you exceed the limit, the API returns 429 RATE_LIMITED. Retry with exponential back-off and respect X-RateLimit-Reset.

Key prefixes

Prefix	Environment
`pp_live_`	Production

Key management

Revoke a key — Go to Integrations → API Keys and click Revoke next to the key. Revocation is instant.
Multiple keys — You can create multiple keys (e.g. one per integration or environment).
Permissions — All keys have full access to your account. Fine-grained scopes are on our roadmap.

Error responses

Status	Code	Cause
`401`	`UNAUTHORIZED`	Missing `X-API-Key` header, key not found, or key has been revoked/expired.
`429`	`RATE_LIMITED`	Too many requests. Check `X-RateLimit-Reset` and retry after the window resets.

Security best practices

Store keys in environment variables (e.g. .env files), never in source code.
Rotate keys periodically or immediately after a suspected leak.
Use separate keys for each environment (staging, production).

Authentication