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

# Permission scopes

> API key scopes for Gather, Connect accounts, and Connect integrations

Every API credential has one or more **permission scopes** that restrict which routes it can call.

<Warning>
  Sending a valid key with the **wrong scope** returns **403 Forbidden** — not 401.
</Warning>

## Scopes

| Scope              | Routes                | Who receives this key                          |
| ------------------ | --------------------- | ---------------------------------------------- |
| **`gather`**       | `/qsi/gather/*`       | Customers using the Gather interview API       |
| **`integrations`** | `/connect/{vendor}/*` | Customer orgs provisioned by a Connect partner |
| **`accounts`**     | `/connect/accounts/*` | Connect **partner master** keys only           |

## Two-tier Connect model

Connect partners receive a **partner master key** (`accounts` scope) to provision customer orgs. Each provisioned customer receives a **customer key** (`integrations` scope) for vendor routes.

```
Partner master key (accounts)
    └── POST /connect/accounts → mints customer key (integrations)
            └── POST /connect/{vendor}/integrations, GET /health, orders, etc.
```

Customer keys **cannot** call `/connect/accounts`. Partner master keys **cannot** call `/connect/{vendor}/*` vendor routes.

## Gather backward compatibility

Existing Gather API keys issued before Connect scopes may have **`gather`** only. They continue to work on `/qsi/gather/*` unchanged.

New Connect-specific keys are minted with explicit scopes in Eucalyptus Connect Partners.

## Examples

<Tabs>
  <Tab title="403 — wrong scope">
    Using a partner master key on a vendor route:

    ```bash theme={null}
    curl -s -o /dev/null -w '%{http_code}\n' \
      "https://connect.humanly.io/connect/stub/health" \
      -H "x-api-key: $PARTNER_MASTER_KEY"
    # → 403
    ```
  </Tab>

  <Tab title="403 — customer on accounts">
    Using a customer key to provision:

    ```bash theme={null}
    curl -s -o /dev/null -w '%{http_code}\n' \
      -X POST "https://connect.humanly.io/connect/accounts" \
      -H "x-api-key: $CUSTOMER_KEY" \
      -H 'Content-Type: application/json' \
      -d '{"externalId":"x","name":"Fail"}'
    # → 403
    ```
  </Tab>
</Tabs>

## Related

* [Account provisioning](/connect/account-provisioning)
* [Authentication](/platform/authentication)
* [Error envelope](/platform/error-envelope) — `FORBIDDEN` code