Authentication

v2 Authentication (Recommended)

All v2 endpoints require your API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Geocoding Key

Location-based endpoints (/v2/charts and /v2/charts/simple) additionally require a Google Geocoding API key:

HD-Geocode-Key: YOUR_GEOCODE_KEY

This key is used to convert location strings (e.g., “Amsterdam, The Netherlands”) into geographic coordinates. You can get one from the Google Cloud Console.

The coordinates endpoint (/v2/charts/coordinates) does not need a geocoding key. If you already have latitude and longitude, use it to skip geocoding entirely.

Full Request Example

curl -X POST https://api.humandesignapi.nl/v2/charts/simple \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "HD-Geocode-Key: YOUR_GEOCODE_KEY" \
  -d '{
    "birthdate": "1990-01-15",
    "birthtime": "14:30",
    "location": "Amsterdam, The Netherlands"
  }'

v1 Authentication (Legacy)

v1 uses a different header format. New integrations should use v2. See the migration guide.

v1 endpoints require two custom headers:

HD-Api-Key: YOUR_API_KEY
HD-Geocode-Key: YOUR_GEOCODE_KEY

The same API key works for both v1 and v2 — only the header name changes.

Access Tiers

Your plan determines which endpoints you can access:

Tier	Endpoints	Plans
Basic	`/v2/charts/simple`, `/v1/bodygraphs/simple`	Hobbyist
Advanced	All endpoints (including `/v2/charts`, `/v2/charts/coordinates`, `/v1/bodygraphs`)	Developer, Scale, Lifetime

Calling an endpoint above your tier returns 403 with error code ACCESS_DENIED.

API Key Security

Keep your API key secret. Never expose it in client-side code, public repositories, or browser requests.

Your API key is available in the dashboard
If your key is compromised, rotate it immediately from the dashboard. The old key is invalidated instantly
Each API call deducts one credit from your plan’s allocation

Authentication Errors

Error Code	Status	Description
`API_KEY_MISSING`	401	No `Authorization` header provided
`API_KEY_INVALID`	401	API key not found or deactivated
`GEOCODE_KEY_MISSING`	401	No `HD-Geocode-Key` header on a location-based endpoint
`GEOCODE_KEY_INVALID`	400	Google Geocoding API key is invalid or restricted
`ACCESS_DENIED`	403	Your plan does not include this endpoint
`ACCOUNT_INACTIVE`	403	Account has been deactivated

Getting Started

Guides

Migration

v2 Authentication (Recommended)

Geocoding Key

Full Request Example

v1 Authentication (Legacy)

Access Tiers

API Key Security

Authentication Errors

​v2 Authentication (Recommended)

​Geocoding Key

​Full Request Example

​v1 Authentication (Legacy)

​Access Tiers

​API Key Security

​Authentication Errors

v2 Authentication (Recommended)

Geocoding Key

Full Request Example

v1 Authentication (Legacy)

Access Tiers

API Key Security

Authentication Errors