Authentication
Two secure ways to connect.
Use an API key for developer calculations. Use HumanDesign.ai OAuth when an MCP client needs a member's permitted account, primary chart, library, reports, or Builder context.
Get a free key
Activate the Free API membership for 100 calls per month, then open your API dashboard to copy the generated key and monitor usage.
REST requests
Use X-Api-Key or Authorization: Bearer on the server. Query-key authentication is deprecated compatibility behavior only: do not use it in new integrations because URLs may be stored in browser, proxy, analytics, and infrastructure logs. For supported bounded, non-streaming consuming operations, a stable Idempotency-Key is strongly recommended. Requests without one remain valid and atomic, but a transport retry after a lost response cannot be deduplicated. Reuse a key only when retrying the identical request. Batch and Server-Sent Events operations reject caller-supplied retry keys and are outside this retry-deduplication contract.
curl "https://api.humandesign.ai/v3/hd-data?Date=1990-05-15T14%3A30%3A00&Timezone=America%2FNew_York" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Idempotency-Key: hdai-example-19900515"Agent HTTP and MCP calculations
Query-string keys are rejected on agent surfaces. Use a Bearer API key or X-Api-Key so credentials do not appear in URLs or request logs. Idempotency-Key is strongly recommended for consuming Agent HTTP tools and unnecessary for free lookups. The MCP calculation catalog is limited to its six published calculation and reference tools; consuming MCP calls require idempotency and the adapter coordinates retry-safe execution.
curl -X POST "https://api.humandesign.ai/agent/v1/tools/resolve-timezone" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Edinburgh"}'HumanDesign.ai account connection
Connect https://mcp.humandesign.ai/ from a compatible MCP client and choose OAuth. The consent screen grants capabilities to one selected workspace and all permitted resources beneath it; it does not ask for separate consent for each project. OAuth requests only identity and session scopes. The server then derives the tools shown from the member's plan, workspace role, live entitlements, and server-derived capability grants.
Keep keys private
- Call the API from your server, edge function or protected automation.
- Never commit keys to source control or expose them in browser JavaScript.
- Rotate a compromised key from your account dashboard.
- Handle 429 responses and show a useful upgrade or retry message.