Authentication: API Keys and Access Scopes Explained

Every request to the Home Service Data API requires an API key passed in the x-api-key request header. Keys are created and managed from your Dashboard and can be scoped to specific datasets and access levels.

Creating an API key

Sign in to your Dashboard.
Navigate to API Keys.
Click Create key and give it a descriptive label (for example, “Production quoting app”).
Copy the key immediately — it will not be shown again in full.
Optionally restrict the key to specific datasets and set a quota.

Treat your API key like a password. Never commit it to source control or include it in client-side code. Use environment variables or a secrets manager.

Passing your key in requests

Include your key in the x-api-key header on every request:

curl -X GET "https://homeservicedata.org/api/v1/finance/fees?trade=solar" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://homeservicedata.org/api/v1/finance/fees?trade=solar', {
  headers: {
    'x-api-key': process.env.HSD_API_KEY!
  }
});

Access levels

Each API key can be granted one of four access levels per dataset:

Level	Description
`none`	No access to this dataset
`sample`	Read a small sample of records (useful for testing data shape)
`sandbox`	Read a broader set of records in a testing context
`production`	Full access to all published, quote-safe records

Your account’s entitlement determines the maximum level you can grant to a key. You can create keys with a lower level than your entitlement — for example, a sample key to share with a developer who is evaluating the API.

Production-level access is required to use data in live customer quotes. See Access Levels for the full policy.

Rate limits and quotas

Every key has a monthly request quota set when it is created. Requests that exceed the quota return a 429 Too Many Requests response. Some endpoints (such as utility territory resolution) also have per-minute request budgets. Operational headers are included on API responses so you can correlate logs and diagnose slow or limited requests:

X-HSD-Request-Id: req_01J...
X-HSD-API-Version: 2026-06-30
X-HSD-Duration-Ms: 42
X-HSD-Performance-State: ok

Rate-limit headers are included when a key-level rate window is evaluated, and on 429 responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
Retry-After: 18

Authentication errors

HTTP status	Meaning
`401 Unauthorized`	Key is missing, malformed, or revoked
`403 Forbidden`	Key exists but does not have access to the requested dataset at the required level
`429 Too Many Requests`	Monthly quota or per-minute rate limit exceeded

{
  "data": null,
  "error": "API key does not have production access to finance_fees.",
  "meta": { "request_id": "req_01J...", "api_version": "2026-06-30" }
}

Managing keys

From the API Keys dashboard page you can:

View the label, last-used date, and access scope for each key
Revoke a key immediately
Create replacement keys with adjusted scopes
Set per-key quotas

Create separate keys for each environment (development, staging, production). Revoke and rotate keys whenever team members change.

Get Started

Core Concepts

Guides

Dashboard

Authentication: API Keys and Access Scopes Explained

Creating an API key

Passing your key in requests

Access levels

Rate limits and quotas

Authentication errors

Managing keys

​Creating an API key

​Passing your key in requests

​Access levels

​Rate limits and quotas

​Authentication errors

​Managing keys

Creating an API key

Passing your key in requests

Access levels

Rate limits and quotas

Authentication errors

Managing keys