Permission scopes - Humanly Developer Docs

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

Sending a valid key with the wrong scope returns 403 Forbidden — not 401.

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

403 — wrong scope
403 — customer on accounts

Using a partner master key on a vendor route:

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

Using a customer key to provision:

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

​Scopes

​Two-tier Connect model

​Gather backward compatibility

​Examples

​Related

Scopes

Two-tier Connect model

Gather backward compatibility

Examples

Related