Authentication
The HomeDash Public API uses simple Bearer tokens. Everything you need to know fits on this page.
The header
Send your API key using either method (Bearer is recommended):
Authorization: Bearer hd_live_… (or hd_sandbox_…)
# or
x-api-key: hd_live_…Missing or malformed header → 401 UNAUTHORIZED. Invalid key → 401 UNAUTHORIZED. Revoked key → 401 REVOKED_KEY.
Key prefixes — live vs sandbox
A key is one or the other; you cannot toggle a key between modes.
hd_live_…Real data, real writes
GET endpoints return your real portfolio. Write endpoints persist to the database, dispatch webhooks, and write audit log entries.
hd_sandbox_…Real reads, mock writes
GET endpoints still return real data so your code sees your actual schema. Write endpoints return realistic mock objects with sandbox: true and never touch the database.
Every response (success or error) includes X-HomeDash-Mode: live or X-HomeDash-Mode: sandbox. Use it to assert the right mode in your CI tests.
Scopes — read_only vs read_write
| Scope | Allowed endpoints | Use it for |
|---|---|---|
| read_only | All GET endpoints | AI assistants, dashboards, analytics, exports |
| read_write | Everything — all GET endpoints plus every POST / PATCH / DELETE write route (rent invoice email, maintenance, tenants, contacts, etc.) | Trusted automation (Zapier writes, invoice email, data entry) |
Calling a write endpoint with a read_only key returns 403 INSUFFICIENT_SCOPE. A read_write key on Professional or Portfolio may call every endpoint, read and write alike.
Plan requirements
| Plan | Reads | Writes | Webhooks |
|---|---|---|---|
| Free | — | — | — |
| Professional | Yes | Yes | Yes |
| Portfolio | Yes | Yes | Yes |
On a non-eligible plan: 403 PLAN_UPGRADE_REQUIRED. Writes are not gated separately by plan — Professional and Portfolio both include them, and a key's own scope decides what it may do.
Rate limits
Limits are per API key, sliding 60-second and 24-hour windows, counted independently for reads vs writes.
| Plan | Reads / min | Writes / min | Reads / day | Writes / day |
|---|---|---|---|---|
| Professional | 100 | 30 | 10,000 | 3,000 |
| Portfolio | 100 | 30 | 10,000 | 3,000 |
Every response carries:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1731930000 (Unix seconds)When you hit the limit you get 429 RATE_LIMIT_EXCEEDED plus a Retry-After header (seconds).
Generating, listing, and revoking keys
Keys live in Dashboard → Developer → API keys. The full secret is shown once at creation time. After that only the prefix is visible. To rotate, generate a new key and revoke the old one. Revocation is immediate — subsequent calls return 401 REVOKED_KEY.
A note on HTTPS
Production traffic must use https://. HomeDash rejects plain HTTP with 403 HTTPS_REQUIRED. localhost over HTTP is allowed in development.
A note on storing keys safely
- Treat the full key like a password. Never commit it to git, paste it in chat, or send it by email.
- For AI assistants, always use a
read_onlykey. - Use a different key per integration so you can revoke one without breaking the others.
- If you suspect a leak, revoke immediately and audit recent calls in the Usage tab.