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

# Account provisioning

> Partner master key lifecycle for Connect customer accounts

Partner-facing account lifecycle at **`/connect/accounts`**. Requires a **partner master API key** with the `accounts` scope. Customer keys (`integrations` scope) cannot call these routes.

<Warning>
  This endpoint requires the **`accounts`** scope. Org-scoped Gather keys and customer Connect keys return **403 Forbidden**.
</Warning>

**Base path:** `{BASE_URL}/connect/accounts` — not `/qsi/connect/accounts`.

## Authentication

<ParamField header="x-api-key" type="string" required>
  Partner master API key with `accounts` scope, linked to a Connect partner (`connectPartnerId`).
</ParamField>

<ParamField header="x-request-id" type="string">
  Optional correlation ID returned in `meta.requestId`. See [Request tracing](/platform/request-tracing).
</ParamField>

## Provision account

Find-or-create a customer organization for your partner.

**Endpoint:** `POST /connect/accounts`

<ParamField body="externalId" type="string" required>
  Your stable customer identifier (scoped per Connect partner).
</ParamField>

<ParamField body="name" type="string" required>
  Organization display name. Must be globally unique when creating a **new** org.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone (e.g. `America/New_York`). Optional; defaults if omitted.
</ParamField>

### Responses

| HTTP    | When                            | `customerApiKey` in response?    |
| ------- | ------------------------------- | -------------------------------- |
| **201** | New org created                 | Yes — store securely; shown once |
| **200** | Same `externalId`, active key   | No                               |
| **200** | Reconnect after disconnect      | Yes — new key                    |
| **409** | `name` taken by a different org | —                                |
| **403** | Not a partner master key        | —                                |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -s -X POST "https://connect.humanly.io/connect/accounts" \
      -H 'Content-Type: application/json' \
      -H "x-api-key: $PARTNER_MASTER_KEY" \
      -d '{
        "externalId": "partner-customer-123",
        "name": "Acme Corp",
        "timezone": "America/New_York"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://connect.humanly.io/connect/accounts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': partnerMasterKey
      },
      body: JSON.stringify({
        externalId: 'partner-customer-123',
        name: 'Acme Corp',
        timezone: 'America/New_York'
      })
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    requests.post(
        'https://connect.humanly.io/connect/accounts',
        headers={'Content-Type': 'application/json', 'x-api-key': partner_master_key},
        json={
            'externalId': 'partner-customer-123',
            'name': 'Acme Corp',
            'timezone': 'America/New_York',
        },
    )
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json 201 Created theme={null}
  {
    "data": {
      "accountId": "uuid",
      "name": "Acme Corp",
      "externalId": "partner-customer-123",
      "connectStatus": "active",
      "customerApiKey": "qapi_customer_key_show_once",
      "isNew": true
    },
    "meta": {
      "requestId": "req_...",
      "timestamp": "2026-06-17T12:00:00.000Z"
    }
  }
  ```
</CodeGroup>

## Get account

**Endpoint:** `GET /connect/accounts/{accountId}`

Returns `accountId`, `name`, `externalId`, `connectStatus` (`active` | `disconnected`), and an `integrations` summary.

## Disconnect account

**Endpoint:** `DELETE /connect/accounts/{accountId}`

Revokes customer Connect API key(s). Does **not** delete the org or integration rows. Returns `connectStatus: disconnected`. Reconnect with another `POST /connect/accounts` using the same `externalId` to receive a new `customerApiKey`.

## Customer key policy

Customer keys minted during provisioning have **`integrations`** scope only — use them for `/connect/{vendor}/*` routes, not for account provisioning.

## Related

* [Permission scopes](/platform/permission-scopes) — `accounts` vs `integrations`
* [Getting started](/connect/getting-started) — end-to-end stub flow
* [Standardized vendor endpoints](/connect/standardized-vendor-endpoints) — after provisioning