Authentication and scopes
Every request carries a bearer key. What that key can call, and which personal fields it can see, is decided by its scopes.
Bearer keys
Authorization: Bearer hlx_live_xxxxxxxxxxxxxxxxxxxxxxxxKeys are stored only as a one-way SHA-256 hash, so we cannot show a key again after it is issued. If one is lost or exposed, ask for a replacement and the old one is revoked immediately. Requests without a key, or with a malformed one, are rejected at our edge before they reach the application.
Environments
| Prefix | Environment | Data | Billing |
|---|---|---|---|
hlx_test_ | Test | Synthetic candidates. Ids start at 9,000,000,000. | Never billed. No credits consumed. |
hlx_live_ | Live | The real pool, limited by your scopes. | Draws on your plan credits. |
Test keys cannot call /v1/chat, /v1/resumes or /v1/feedback (they would touch real data) and get 403 test_key; they also cannot register webhooks or start a payment. Test and live keys are separate keys: build against test, switch the key to go live. Nothing else changes.
Scopes
Scopes come in two kinds. Endpoint scopes decide which routes a key may call:
| Scope | Allows |
|---|---|
search | POST /v1/search, GET /v1/candidates/{id} |
match | POST /v1/match, POST /v1/fit |
parse | POST /v1/parse/resume, POST /v1/parse/jd |
market | /v1/market/pay-bands, /skills, /overview |
jobs | /v1/jobs, /v1/jobs/{slug} |
chat | POST /v1/chat (anonymised conversational search, streamed) |
ingest | POST /v1/resumes (contribute resumes to the pool) |
feedback | POST /v1/feedback |
Field scopes decide what personal data appears in candidate records returned by search, match and the candidate endpoint:
| Scope | Adds to the record |
|---|---|
pii:contact | contact: name, email, phone, LinkedIn and portfolio URLs, current company. |
pii:comp | compensation: current fixed and variable pay, expected pay (INR lakh per annum), notice period, serving notice, employment status. |
pii:docs | cv: a short-lived resume download link. Also required for GET /v1/candidates/{id}/cv. |
Compensation is what the candidate reported about themselves. It is not verified and should be treated as a signal, not a fact. Every release of contact, pay or document fields is written to an access log tied to your key.
IP allowlists
A key can be locked to specific source IP addresses. A request from anywhere else gets 403 ip_not_allowed. We recommend this for any server with a fixed egress address. Ask for it when your key is issued or change it later by contacting support@helixhumancapital.in.
Key lifecycle
- Rotation: request a new key, deploy it, then ask us to revoke the old one. Both work until then.
- Revocation: immediate. Revoked or disabled keys get
403 key_disabled. - Expiry: a paid key whose period has ended, after the grace window, gets
402 subscription_inactive. See Credits and billing.