Authentication

HLD APIs use API keys for server-to-server authentication and OAuth 2.0 for user-delegated access. All communication must use HTTPS.

API keys

API keys are long-lived credentials scoped to a specific tenant and set of permissions. They are the recommended method for backend integrations and automated pipelines.

Key format

All API keys follow the pattern hld_live_<32-char-random> for production and hld_test_<32-char-random> for the sandbox environment.

Sending the key

bash

curl https://api.hldgroup.org/v1/tenants \
  -H "Authorization: Bearer hld_live_xxxxxxxxxxxxxxxxxxxx"

Warning:Never send API keys in query parameters or request bodies. The Authorization header is the only accepted method.

API key scopes

Keys can be restricted to one or more permission scopes. Grant only what your integration needs.

Name	Type	Required	Description
tenants:read	string	No	Read tenant profiles and configuration.
tenants:write	string	No	Create and update tenant records.
alerts:read	string	No	Read security alerts and threat events.
alerts:write	string	No	Acknowledge, escalate, or close alerts.
devices:read	string	No	Read enrolled device inventory.
identity:read	string	No	Read identity and access records.
compliance:read	string	No	Read compliance posture and evidence.
sentinel:read	string	No	Read incident data from HLD Sentinel.
sentinel:respond	string	No	Trigger automated response actions.
webhooks:manage	string	No	Create and manage webhook endpoints.

OAuth 2.0

OAuth 2.0 is used when your application acts on behalf of a HomeBase user. The authorization code flow with PKCE is the only supported grant type for public clients.

Authorization endpoint

bash

GET https://auth.hldgroup.org/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=tenants:read alerts:read
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
  &state=RANDOM_STATE

Token exchange

bash

POST https://auth.hldgroup.org/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=YOUR_CODE_VERIFIER

Token response

json

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "hld_rt_xxxxxxxxxxxxxxxxxxxx",
  "scope": "tenants:read alerts:read"
}

Token expiry and refresh

Access tokens expire after 1 hour. Use the refresh token to obtain a new one without re-prompting the user.

bash

POST https://auth.hldgroup.org/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=hld_rt_xxxxxxxxxxxxxxxxxxxx
&client_id=YOUR_CLIENT_ID

Tip:Refresh tokens are single-use. Each refresh returns a new refresh token — store the latest one and discard the old.

HomeBase API Webhooks