Authentication

All WorkFunder API requests require authentication via an API key passed in the Authorization header.

API Key Types

WorkFunder issues two types of API keys, distinguished by their prefix:

Prefix	Environment	Behavior
wf_live_	Production	Creates real tasks, charges real money, workers are assigned
wf_test_	Sandbox	No real charges, tasks auto-fund, simulated worker flow

API keys are 40+ characters long. The first 20 characters (prefix + partial secret) are stored for lookup; the full key is hashed with bcrypt and never stored in plaintext.

Generating Keys

Generate API keys from the Dashboard or via the API:

curl -X POST https://api.workfunder.com/v1/account/keys \
  -H "Authorization: Bearer wf_live_existing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "environment": "live"
  }'

caution

API keys are shown only once at creation time. Store them securely. If a key is lost or compromised, revoke it immediately and generate a new one.

Revoking Keys

curl -X DELETE https://api.workfunder.com/v1/account/keys/key_id_here \
  -H "Authorization: Bearer wf_live_your_key"

Revoked keys immediately stop working. Existing requests in-flight may still complete, but no new requests will be accepted.

Authorization Header

Pass your API key as a Bearer token in the Authorization header:

curl https://api.workfunder.com/v1/tasks \
  -H "Authorization: Bearer wf_live_your_api_key_here"

The API key determines:

• Identity -- Which developer account the request belongs to
• Environment -- Whether the request operates in live or test mode
• Rate limits -- Based on the developer's subscription tier

Rate Limits

Rate limits are enforced per API key on a per-minute sliding window. Limits vary by subscription tier:

Tier	Requests/Minute	Tasks/Month	Price
Free	10	50	$0
Growth	100	500	$99/mo
Pro	500	Unlimited	$499/mo
Enterprise	2,000	Unlimited	Custom

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1708790400

Exceeding the Rate Limit

When the rate limit is exceeded, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Best practices for handling rate limits:

• Respect the X-RateLimit-Remaining header
• Implement exponential backoff on 429 responses
• Cache responses where appropriate (e.g., task details that have not changed)
• Use webhooks instead of polling to reduce API calls

Error Codes

Authentication-related error responses:

MISSING_API_KEY (401)

No API key was provided in the request.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "An API key is required to access this resource."
  }
}

Fix: Include the Authorization: Bearer <key> header in your request.

INVALID_API_KEY (401)

The provided API key does not match any active key.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid."
  }
}

Fix: Verify you are using the correct key. Check for whitespace or truncation. Generate a new key if needed.

REVOKED_API_KEY (401)

The API key has been revoked.

{
  "error": {
    "code": "REVOKED_API_KEY",
    "message": "The provided API key has been revoked."
  }
}

Fix: Generate a new API key from the dashboard.

RATE_LIMIT_EXCEEDED (429)

Too many requests in the current time window.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Fix: Wait for the rate limit window to reset (check X-RateLimit-Reset header), or upgrade your tier for higher limits.

TASK_LIMIT_EXCEEDED (403)

Monthly task creation limit reached for your tier.

{
  "error": {
    "code": "TASK_LIMIT_EXCEEDED",
    "message": "You have exceeded your monthly task limit for this tier."
  }
}

Fix: Upgrade to a higher tier, or wait until the next billing cycle.

Security Best Practices

1. Never expose API keys in client-side code. Always call the WorkFunder API from your server.
2. Use environment variables to store API keys -- never hardcode them in source files.
3. Use test keys for development. Only use live keys in production environments.
4. Rotate keys periodically. Revoke and regenerate keys on a regular schedule.
5. Use separate keys for different environments (staging, production) and services.
6. Monitor key usage in the dashboard to detect unauthorized access.

# Good -- store in environment variable
export WORKFUNDER_API_KEY="wf_live_..."

# Use in your application
curl https://api.workfunder.com/v1/tasks \
  -H "Authorization: Bearer $WORKFUNDER_API_KEY"