Skip to main content
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.
API credentials are created in Eucalyptus (internal admin). Contact your Humanly administrator or partner success contact for keys.

​
Key format

  • Prefix: qapi_ followed by a secure random string
  • Example: qapi_abc123def456... (placeholder — never use real keys in docs or logs)

​
Gather vs Connect

See Permission scopes for the full matrix.

​
Authentication by route

​
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:
This is a legacy encoding of your 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.

​
Accounts and vendor meta routes — API key only

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:
  1. x-api-key — Connect customer key (integrations scope). Used when a partner provisions the customer through Connect.
  2. 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

​
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/*.