# HubSpot: connecting

The assistant reads from HubSpot who is writing to it: the contact and the
company, deals and support tickets. It never writes to HubSpot. What exactly
it may read, you decide for each mailbox separately. How connections work in
draften in general is described on the [Integrations](/en/admin/integrations)
page.

## What you need

- A HubSpot account with **super admin** rights (or with the **Developer tools
  access** permission) — only such an account can create an API key.
- In draften, an **owner or manager of the organisation**.

draften needs an **API key with read scopes only**. HubSpot issues it today
as a **service key**. Older accounts may also have an earlier **private app**
token (it starts with `pat-`); it keeps working, only HubSpot no longer lets
you create new private apps.

## In HubSpot: service key

1. Open the list of keys: in the main menu, **Development** → **Keys** →
   **Service keys** (in some accounts **Settings** → **Integrations** →
   **Service Keys**).
2. At the top right, click **Create service key** and name the key, for
   example `draften`.
3. Click **Add new scope**. In the panel on the right, search (the **Find
   a scope** field) and tick only these read scopes:
   - `crm.objects.contacts.read` — contacts,
   - `crm.objects.companies.read` — companies,
   - `crm.objects.owners.read` — who looks after the contact,
   - `crm.objects.deals.read` — deals,
   - `crm.objects.tickets.read` — tickets.

   Add nothing with `.write`. A key can only get the scopes its creator has.
4. Create the key. On its page, click **Show** and then **Copy**.

You can **replace** the key later (**Rotate and expire now**, or **Rotate and
expire later** — the old one then stays valid for 7 more days). Paste the new
key into draften (below).

## In draften

1. Open Organisation → **Integrations** and, in the **Integrations** card,
   fill in:
   - **System** — **HubSpot**,
   - **Name** — for example `HubSpot - sales and support`,
   - **Access secret** — the copied key.

   Click **Add connection**. The key is stored encrypted and never shown
   again.
2. In the connection's row, open the **⋯** menu → **Test the connection**. In
   a moment it shows "Connection fine (…)". Missing scopes are listed under
   "Not available with this token:"; when the key has write scopes too, the
   test points that out.
3. In the **Which mailboxes may use the connection** part, click **Grant** by
   a mailbox, tick what the assistant may read and click **Save the grant**:
   - **Contact and company**,
   - **Deals** and, under it, **Deal amounts**,
   - **Support tickets** and, under it, **Ticket detail** and **Internal
     notes of a ticket**.
4. The assistant's editor then adds, in the assistant's Settings →
   **Knowledge**, a source of the **external system** kind and chooses what
   the assistant really reads — see
   [Connecting a CRM and other systems](/en/connecting-a-crm).

When you replace the key, paste the new one into **New access secret** by the
connection and click **Replace**; then **Test the connection** again.

## Connection test errors

The test's message is in English, straight from HubSpot or from draften:

| In the message | What it means | What to do |
|---|---|---|
| `the access token was refused (401)` | HubSpot did not accept the key — a typo, or the key was replaced or deleted | paste a valid key |
| `… lacks a scope for this read (403)` | the key is missing a read scope | add the scope to the key in HubSpot |
| `HubSpot rate limit reached (429)` | the API call limit is used up | try later |
| `HubSpot answered HTTP …` | another answer from HubSpot | try again; if it persists, replace the key |