Security & Protocol Reference

Authentication & Request Headers

The CVFormatter REST API secures all incoming traffic using industry-standard Bearer token authentication over Transport Layer Security (TLS 1.3). Every call validates your secret key against organization-level role permissions, active credit pools, and endpoint-specific rate quotas.

How CVFormatter API authentication works

All API interactions require an active secret token prefixed with cvf_live_ (for production workloads) or cvf_test_ (for sandbox environments). Our API gateway extracts the token from the HTTP request, authenticates the signing tenant, verifies that required OAuth scopes are present, and attaches tenant metadata to your request context.

API Security Best Practices

Server-to-Server Only: Never expose CVFormatter secret keys in client-side JavaScript bundles, single-page applications (SPAs), or mobile binaries.
Environment Storage: Load API tokens via secured server environment variables (e.g., CVF_API_KEY) or secrets managers such as AWS Secrets Manager, Vault, or GCP Secret Manager.
Automatic Revocation: If an API credential is accidentally committed to a public version-control repository, invalidate it immediately from the CVFormatter Developer Console.

Required & optional HTTP request headers

Include the following standard and custom HTTP headers with every call to endpoints rooted at https://api.cvformatter.co/api/v1/public:

Header	Specification & Value	Required
Authorization	`Bearer <token>`. RFC 6750 Bearer authentication string. Transmits your organization or recruiter API key generated within the dashboard.	Required (unless using fallback)
x-api-key	Alternative header accepting the raw token string directly. Provided for legacy integration tools, Enterprise Service Buses (ESB), or webhooks unable to construct formatted `Authorization` headers.	Optional fallback
Idempotency-Key	A unique client-supplied UUIDv4 (8–128 ASCII characters). Protects against network dropouts, accidental duplicate form submissions, and duplicate resume parsing credit deductions.	Mandatory on `POST /resumes` and reprocess
cvf-version	Explicit API release date pinning (e.g., `2026-04-01`). Pinning the version prevents field additions or breaking schema mutations from impacting production parsing pipelines.	Optional (defaults to latest)
Content-Type	Specifies document serialization format: `multipart/form-data` for binary CV uploads, and `application/json` for metadata mutations, patching titles, and template exports.	Required on POST / PATCH

Verifying your key & checking token permissions

Before deploying automated extraction jobs or Applicant Tracking System (ATS) integrations, verify that your credentials are valid by querying the GET /me identity endpoint. This returns your associated organization ID, account tier, and assigned permission scopes without consuming resume processing credits.

curl "https://api.cvformatter.co/api/v1/public/me" \
  -H "Authorization: Bearer cvf_live_839f28a01bf9e2" \
  -H "cvf-version: 2026-04-01"

Response Preview (200 OK)

{
  "organization_id": "org_9182ab3",
  "key_type": "organization",
  "integration_user_id": "usr_system_ats",
  "scopes": ["resumes:read", "resumes:write", "resumes:export", "credits:read"]
}

Organization keys vs. Recruiter keys

CVFormatter separates system-level automation credentials from individual staff credentials. Choosing the correct key architecture ensures proper candidate attribution, audit logging, and uninterrupted webhook delivery.

Organization Key (Recommended for ATS / CI)

Company-wide integration keys provisioned by system administrators. Ideal for backend pipelines such as Workday, Greenhouse, Bullhorn, Zapier, and custom internal ATS portals.

Consumes pooled company credits (Subscription & Pay-as-you-go).
Independent of employee turnover; remains active when staff leave.
Allows assigning uploads to any recruiter via recruiter_id.

Recruiter Key (Individual Seat)

Personal keys generated by individual team members for desktop tooling, local scripts, or browser extensions.

All submitted resumes automatically inherit that recruiter’s user identity.
Revoked immediately if the user is suspended or removed from the workspace.
Restricted: Cannot access tenant management or recruiter assignment APIs.

Authentication error codes & diagnostics

When an API request fails authentication or authorization checks, the gateway responds with standard RFC 7807 problem details in JSON format:

HTTP Status	Error Code	Resolution Guide
401 Unauthorized	UNAUTHORIZED	The token is missing, malformed, or expired. Verify the Bearer prefix and token string in your `Authorization` header.
403 Forbidden	ORGANIZATION_KEY_REQUIRED	You attempted to query a tenant-level endpoint (such as `GET /recruiters`) using an individual recruiter token.
403 Forbidden	SCOPE_UNAUTHORIZED	Your key does not possess the requisite permission scope (e.g., `resumes:export` or `credits:read`). Generate a new token with elevated scopes.