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

# Create an API Key

> Generate a Private Integration key to authenticate your API requests — no OAuth required.

There are two ways to authenticate with the HoopAI API:

| Method                      | Best for                                           |
| --------------------------- | -------------------------------------------------- |
| **Private Integration key** | Your own account — instant setup, long-lived token |
| **OAuth 2.0**               | Marketplace apps that access other users' accounts |

For getting started, use a **Private Integration key**. It's the fastest path to a working API call.

## Create a Private Integration

<Steps>
  <Step title="Open Settings">
    In your HoopAI dashboard, click **Settings** in the left sidebar.
  </Step>

  <Step title="Go to Private Integrations">
    Select **Integrations**, then click **Private Integrations**.
  </Step>

  <Step title="Create a new integration">
    Click **+ Add Integration**. Give it a clear name — something like `My Automation` or `Data Sync Script`.

    <Frame caption="Creating a new Private Integration">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/hoopai-84ec0cdc/images/settings-private-integration-create.png" alt="Create Private Integration" />
    </Frame>
  </Step>

  <Step title="Select permissions">
    Choose only the scopes your integration needs. Granting fewer permissions reduces risk if a key is exposed.

    <Frame caption="Selecting permission scopes for your integration">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/hoopai-84ec0cdc/images/settings-private-integration-scopes.png" alt="API Permission Scopes" />
    </Frame>

    **Common scopes:**

    | Scope                      | What it allows                           |
    | -------------------------- | ---------------------------------------- |
    | Contacts (Read/Write)      | Get, create, update, and delete contacts |
    | Conversations (Read/Write) | Read threads, send messages              |
    | Calendars (Read/Write)     | List calendars, create appointments      |
    | Opportunities (Read/Write) | Manage deals and pipeline stages         |
    | Payments (Read)            | View invoices and transactions           |
  </Step>

  <Step title="Save and copy your key">
    Click **Save**. Your API key appears once — copy it now and store it securely.

    <Warning>
      This key will not be shown again after you leave the page. Save it in a password manager or environment variable immediately.
    </Warning>
  </Step>
</Steps>

## Using your key in requests

Every API request requires two headers:

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

| Header          | Value                 | Purpose                                             |
| --------------- | --------------------- | --------------------------------------------------- |
| `Authorization` | `Bearer YOUR_API_KEY` | Authenticates your request                          |
| `Version`       | `2021-07-28`          | Pins the API to a stable version — always send this |

## Keep your key secure

* Never commit API keys to git — use environment variables
* Use separate keys for development and production
* Rotate keys immediately if you suspect exposure
* Delete unused integrations to reduce your attack surface

## When to use OAuth instead

Switch to OAuth 2.0 when you're building an app that needs to access **other users'** HoopAI accounts (e.g., a marketplace app). See the [OAuth 2.0 guide](/api-reference/oauth/overview) for the full setup.

## Next step

<Card title="Make your first request" icon="terminal" href="/developer/getting-started/first-request">
  Test your key with a live API call and see what comes back
</Card>