Authentication - Hostreach

API keys

All requests to the Hostreach public API must include an API key. Keys are scoped, revocable, and prefixed to indicate the environment.

Environment	Prefix	Example
Live	`hr_live_`	`hr_live_a1b2c3d4_...`
Test	`hr_test_`	`hr_test_a1b2c3d4_...`

Use hr_live_ keys for production integrations and hr_test_ keys for development and testing.

You can pass the key in either of two ways:

curl https://api.hostreach.io/v1/public/v1/me \
  -H "X-Api-Key: hr_live_your_key_here"

curl https://api.hostreach.io/v1/public/v1/me \
  -H "Authorization: Bearer hr_live_your_key_here"

API keys can be restricted to specific scopes. An empty scopes array means full access (wildcard).

Scope	Access granted
`campaigns:read` / `write`	List, create, update campaigns
`leads:read` / `write`	List, update, delete leads and notes
`extractions:read` / `write`	Start and inspect extraction jobs
`platforms:read`	Platform filter schemas and location search
`messaging:read` / `write`	Read/send WhatsApp messages
`templates:read` / `write`	Message templates
`accounts:read` / `write`	WhatsApp accounts
`valuations:read` / `write`	Property valuations
`fichas:read` / `write`	Listing sheets
`scheduling:read` / `write`	Event types and appointments
`webhooks:read` / `write`	Webhook subscriptions

A 403 Forbidden response means the key is valid but lacks the required scope for that endpoint. Create a new key with the necessary scope.

All errors return a JSON body:

{
  "statusCode": 401,
  "message": "Invalid or missing API key"
}

Status	Cause
`401`	Missing or invalid API key
`403`	Key valid but missing required scope
`429`	Rate or quota limit reached

To rotate a key: create a new key, update your integration, then revoke the old one.
To revoke: go to Settings › Workspace › Acceso API and click Revoke next to the key.
Revoked keys return 401 immediately.