Humanly APIs authenticate with an x-api-key header. The key encodes organization (and often team) context — you do not pass a separate organization ID for most routes.
x-api-key: qapi_your_api_key_here
API credentials are created in Eucalyptus (internal admin). Contact your Humanly administrator or partner success contact for keys.
- Prefix:
qapi_ followed by a secure random string
- Example:
qapi_abc123def456... (placeholder — never use real keys in docs or logs)
Gather vs Connect
| Product | Route prefix | Typical key |
|---|
| Gather | /qsi/gather/* | Org/team key with gather scope |
| Connect accounts | /connect/accounts/* | Partner master key with accounts scope |
| Connect vendors | /connect/{vendor}/* | Customer key with integrations scope |
Authentication by route
| Routes | Auth |
|---|
Gather /qsi/gather/* | Gather API key via x-api-key (see below for legacy transport) |
Connect accounts /connect/accounts/* | x-api-key only — partner master key (accounts scope) |
| Connect vendor meta (integrations, health, config) | x-api-key only — customer Connect key (integrations scope) |
| Connect vendor data (orders, catalog, results, …) | x-api-key (partner) or Authorization: Basic (legacy direct integration) |
Gather
All Gather routes require a Gather API key with the gather scope. Pass it in the x-api-key header — this is the supported method for new integrations.
Gather legacy Basic auth (transport only)
Some older Gather clients send the same Gather API key using Basic auth instead of the header:
Authorization: Basic base64(organizationId:apiKey)
qapi_ Gather key. It is not ATS or HRIS integration credentials. Prefer x-api-key for all new work. Details: Gather authentication.
Connect
Connect auth depends on the route type.
These routes accept x-api-key only:
/connect/accounts/* — partner master key (accounts scope)/connect/{vendor}/integrations, vendor health, config validation — customer Connect key (integrations scope)
Vendor data routes — dual auth (legacy parity)
Some data routes (for example orders and catalog reads) support two auth paths:
x-api-key — Connect customer key (integrations scope). Used when a partner provisions the customer through Connect.Authorization: Basic — direct legacy integration credentials, validated the same way as pre-Connect per-vendor routes on the integration host.
If both headers are sent and the x-api-key is valid for the route scope (customer key with integrations scope), it takes precedence over Basic auth. Wrong-scope keys return 403 — Connect does not fall back to Basic auth.
See Build a vendor integration and Connect overview.
Example request
Gather (cURL)
Connect (cURL)
curl -X GET "https://api.prod.qualifi.hr/qsi/gather/questions" \
-H "x-api-key: qapi_your_gather_key"
curl -X GET "https://connect.humanly.io/connect/stub/health" \
-H "x-api-key: qapi_your_customer_key"
Dual domain
Gather examples historically use api.prod.qualifi.hr. Connect examples use connect.humanly.io as canonical. Both hosts run the same handlers — see Connect overview.
Gather routes are also reachable at connect.humanly.io/qsi/gather/*.
