> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Shared API key authentication for Gather and Connect

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
```

<Callout type="info">
  API credentials are created in **Eucalyptus** (internal admin). Contact your Humanly administrator or partner success contact for keys.
</Callout>

## 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

| 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   |

See [Permission scopes](/platform/permission-scopes) for the full matrix.

## 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)
```

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](/getting-started/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](/connect/build-a-vendor-integration) and [Connect overview](/connect/overview).

## Example request

<Tabs>
  <Tab title="Gather (cURL)">
    ```bash theme={null}
    curl -X GET "https://api.prod.qualifi.hr/qsi/gather/questions" \
      -H "x-api-key: qapi_your_gather_key"
    ```
  </Tab>

  <Tab title="Connect (cURL)">
    ```bash theme={null}
    curl -X GET "https://connect.humanly.io/connect/stub/health" \
      -H "x-api-key: qapi_your_customer_key"
    ```
  </Tab>
</Tabs>

## 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](/connect/overview).

Gather routes are also reachable at `connect.humanly.io/qsi/gather/*`.

## Related

* [Gather authentication](/getting-started/authentication) — Gather-specific details
* [Permission scopes](/platform/permission-scopes)
* [Request tracing](/platform/request-tracing)