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

# Authentication

> All API requests authenticate with a Private Integration key and your Location ID.

The HoopAI API uses **Private Integration keys** for authentication. Every request must include your key as a Bearer token, plus the API version header.

## Required headers

| Header          | Value                 | Required                |
| --------------- | --------------------- | ----------------------- |
| `Authorization` | `Bearer YOUR_API_KEY` | Always                  |
| `Version`       | `2021-07-28`          | Always                  |
| `Content-Type`  | `application/json`    | POST / PUT / PATCH only |

Omitting `Version` will cause unexpected errors.

## Example request

```bash theme={null}
curl https://services.leadconnectorhq.com/contacts/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Version: 2021-07-28"
```

## Getting started

<Steps>
  <Step title="Find your Location ID">
    Go to **Settings > Business Profile**. Your Location ID is shown at the top right.

    [See detailed steps](/developer/getting-started/location-id)
  </Step>

  <Step title="Create a Private Integration key">
    Go to **Settings > Integrations > Private Integrations**. Click **Add Integration**, name it, select permissions, and save.

    [See detailed steps](/developer/getting-started/api-keys)
  </Step>

  <Step title="Make your first request">
    Use your key in the Authorization header and your locationId as a query parameter.

    [See example requests](/developer/getting-started/first-request)
  </Step>
</Steps>

## Permission scopes

When creating a Private Integration key, select only the scopes your integration needs:

| Scope                 | Access granted                         |
| --------------------- | -------------------------------------- |
| Contacts (Read)       | List and retrieve contacts             |
| Contacts (Write)      | Create, update, delete contacts        |
| Conversations (Read)  | Read conversation threads and messages |
| Conversations (Write) | Send messages                          |
| Calendars (Read)      | List calendars and appointments        |
| Calendars (Write)     | Create and manage appointments         |
| Opportunities (Read)  | Read deals and pipeline data           |
| Opportunities (Write) | Create and update opportunities        |
| Payments (Read)       | View invoices and transactions         |

## Error responses

| Status | Meaning                  | Fix                                                |
| ------ | ------------------------ | -------------------------------------------------- |
| `401`  | Missing or invalid key   | Check your `Authorization` header                  |
| `403`  | Key lacks required scope | Add the scope in Private Integrations settings     |
| `429`  | Rate limit exceeded      | Max 100 requests / 10 seconds. Back off and retry. |