Authentication

The HoopAI Platform API uses OAuth 2.0 for authentication. Every API request must include a valid access token.

Authentication methods

Method	Best for	Token lifetime
Private Integration	Internal tools, testing, quick prototypes	Long-lived (account scoped)
OAuth 2.0 Authorization Code	Marketplace apps, multi-tenant integrations	24 hours (refresh to renew)

Required headers

Every API request must include these headers:

Header	Value	Required
`Authorization`	`Bearer <access_token>`	Always
`Version`	`2021-07-28`	Always
`Content-Type`	`application/json`	For POST/PUT/PATCH

curl -X GET "https://services.leadconnectorhq.com/contacts/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

The Version header is required on every request. Omitting it will result in unexpected behavior or errors.

Option 1: Private integrations

Private Integrations are the fastest way to get started. They generate a scoped API key tied to a single account.

Navigate to settings

Go to Settings > Integrations > Private Integrations in your HoopAI account.

Create a new integration

Click Create Integration, give it a name, and select the scopes (permissions) your integration needs.

Copy the API key

Copy the generated API key. Use it as a Bearer token in your requests.

Private Integration keys are scoped to a single account and do not expire automatically. Treat them like passwords — store them securely and rotate them periodically.

Option 2: OAuth 2.0 authorization code flow

For marketplace apps or multi-tenant integrations, use the standard OAuth 2.0 Authorization Code flow.

Step 1: Register your app

Create an app in the HoopAI Marketplace. You’ll receive:

Client ID — identifies your app
Client Secret — used to exchange the authorization code for tokens

Step 2: Redirect to authorize

Send the user to the authorization URL:

https://marketplace.gohighlevel.com/oauth/chooselocation?response_type=code&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&scope=contacts.readonly conversations.readonly

Parameter	Description
`response_type`	Always `code`
`redirect_uri`	Your registered callback URL
`client_id`	Your app’s Client ID
`scope`	Space-separated list of OAuth scopes

Step 3: Exchange the code for tokens

After the user authorizes, they’re redirected to your redirect_uri with a code parameter. Exchange it:

curl -X POST "https://services.leadconnectorhq.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "cJl2b3Qx...",
  "scope": "contacts.readonly conversations.readonly",
  "locationId": "loc_abc123",
  "companyId": "comp_xyz789"
}

Step 4: Refresh the token

Access tokens expire after 24 hours. Use the refresh token to get a new one:

curl -X POST "https://services.leadconnectorhq.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Refresh tokens are single-use. Each time you refresh, you get a new access_token and a new refresh_token. Store the new refresh token for the next cycle.

Token scopes

Scopes control what your app can access. Request only the scopes you need.

Scope	Access
`contacts.readonly`	Read contacts
`contacts.write`	Create, update, delete contacts
`conversations.readonly`	Read conversations and messages
`conversations.write`	Send messages
`calendars.readonly`	Read calendars and appointments
`calendars.write`	Create and manage appointments
`opportunities.readonly`	Read pipeline data
`opportunities.write`	Manage opportunities

See the full scopes reference for every available scope.

Security best practices

Store tokens securely

Never store access tokens or refresh tokens in client-side code, version control, or logs. Use environment variables or a secrets manager.

Use minimal scopes

Request only the permissions your app actually needs. This limits exposure if a token is compromised.

Handle token expiration gracefully

Build automatic refresh logic into your integration. If a refresh fails, prompt the user to re-authorize.

Validate webhook signatures

When receiving webhooks, always verify the signature to ensure the payload came from HoopAI.

First Steps

Guides

Authentication methods

Required headers

Option 1: Private integrations

Option 2: OAuth 2.0 authorization code flow

Step 1: Register your app

Step 2: Redirect to authorize

Step 3: Exchange the code for tokens

Step 4: Refresh the token

Token scopes

Security best practices

Next steps

OAuth scopes reference

Making requests

First Steps

Guides

​Authentication methods

​Required headers

​Option 1: Private integrations

​Option 2: OAuth 2.0 authorization code flow

​Step 1: Register your app

​Step 2: Redirect to authorize

​Step 3: Exchange the code for tokens

​Step 4: Refresh the token

​Token scopes

​Security best practices

​Next steps

OAuth scopes reference

Making requests

Authentication methods

Required headers

Option 1: Private integrations

Option 2: OAuth 2.0 authorization code flow

Step 1: Register your app

Step 2: Redirect to authorize

Step 3: Exchange the code for tokens

Step 4: Refresh the token

Token scopes

Security best practices

Next steps