Authentication

Secure access to human resources. Trust, but verify.

The HaaS API uses API keys to authenticate requests. You can view and manage your API keys in the HaaS Dashboard. Authentication is required for all endpoints except the public health check.

API Keys

HaaS provides two types of API keys. Use the right one for your environment to avoid accidentally dispatching tasks to real humans during development (they find this confusing and will leave negative reviews).

Key Type Prefix Purpose
Test Keys haas_test_ Development and testing. Tasks are routed to simulated humans.
Live Keys haas_live_ Production use. Tasks are dispatched to real, breathing humans.
🧪
Test mode humans: Our simulated humans are trained on real behavioral data. They procrastinate realistically, have mood swings, and occasionally forget what they were doing. Perfect for testing your error handling.

Using Your API Key

Include your API key in the Authorization header as a Bearer token with every request.

Request Headers 
Authorization: Bearer haas_live_sk_7Kq8mP2xNvL3...
Example: Check a Human's Availability 
curl https://api.api4human.com/v1/humans/usr_maria_42/status \
  -H "Authorization: Bearer haas_live_sk_7Kq8mP2xNvL3..."
🔐
Keep your keys secret: Never expose API keys in client-side code, public repositories, or logs. If a key is compromised, rotate it immediately from the dashboard. Humans will forgive you, but only once.

Human Consent (OAuth 2.0)

Before you can dispatch tasks to a specific human, they must grant your application access. This uses a standard OAuth 2.0 authorization flow. We take consent seriously—humans cannot be allocated without their explicit agreement.

Authorization Flow

1. Redirect to Authorization

Send the human to our authorization page where they can review your application and decide whether to grant access.

Authorization URL 
https://auth.api4human.com/authorize?
  client_id=your_client_id
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=tasks:dispatch status:read
  &state=random_csrf_token

2. Human Reviews and Approves

The human sees what permissions you are requesting. They may accept, deny, or close the tab and forget about it entirely (handle this case gracefully).

3. Exchange Code for Token

If approved, we redirect back to your app with an authorization code. Exchange it for an access token.

Token Exchange Request 
POST https://auth.api4human.com/token

{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "redirect_uri": "https://your-app.com/callback",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}
Token Exchange Response 
{
  "access_token": "haas_at_Kj7mNq2xPvL8...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "haas_rt_Xm9pQw4zRtY2...",
  "scope": "tasks:dispatch status:read",
  "human_id": "usr_maria_42"
}

Available Scopes

Scope Description
status:read View the human's current status, energy, mood, and availability.
tasks:dispatch Send tasks to the human for completion.
tasks:read View task history and completion statistics.
communication:realtime Open WebSocket connections for real-time updates.
profile:read Access human profile information (skills, preferences).
🤝
Request minimal scopes: Only ask for what you need. Humans are more likely to approve applications with focused, limited permissions. Requesting * scope will cause most humans to immediately close the authorization page.

Rate Limiting

To protect both our infrastructure and our human endpoints (who can only process so many requests), we enforce rate limits based on your plan tier.

Plan Requests/min Concurrent Tasks Humans
Free 60 5 3
Pro 300 25 20
Enterprise 1000 100 Unlimited

Rate Limit Headers

Every response includes headers indicating your current rate limit status.

Rate Limit Headers 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1705329600

Handling 429 Responses

When you exceed your rate limit, you will receive a 429 Too Many Requests response. Unlike with servers, being too demanding with humans does not just slow you down—it may affect your reputation.

Rate Limit Exceeded Response 
{
  "error": {
    "code": 429,
    "type": "rate_limit_exceeded",
    "message": "Slow down. Even machines benefit from patience.",
    "retry_after": 32,
    "suggestion": "Consider batching requests or upgrading your plan."
  }
}

Security Best Practices

🔄

Rotate Keys Regularly

Generate new API keys periodically. Old keys can be revoked without downtime using key rolling.

🌍

Use Environment Variables

Never hardcode keys. Store them in environment variables or a secrets manager.

📝

Audit Access Logs

Review your API access logs regularly. Unusual patterns may indicate compromise or misconfiguration.

🛡️

Restrict by IP

Enterprise plans support IP allowlisting. Limit API access to known infrastructure.

🚨
Compromised key? If you suspect a key has been exposed, revoke it immediately from the dashboard. Then apologize to any humans who received unexpected tasks—they appreciate the courtesy.

Token Refresh

Human consent tokens expire after one hour. Use the refresh token to obtain a new access token without requiring the human to re-authorize.

Refresh Token Request 
POST https://auth.api4human.com/token

{
  "grant_type": "refresh_token",
  "refresh_token": "haas_rt_Xm9pQw4zRtY2...",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}
⏰
Refresh tokens expire too: Refresh tokens are valid for 30 days. If a human has not interacted with your application in a month, they will need to re-authorize. This is by design—long-dormant permissions should require re-consent.

Ready to dispatch your first task?

Now that you are authenticated, learn how to submit tasks to humans and monitor their progress.

Explore the Tasks API