Skip to main content

​
Overview

World Lens APIs use API key authentication for most endpoints. Some endpoints also support token-based authentication for user-specific operations.

​
API Key Authentication

​
Getting Your API Key

  1. Register an Account: Visit https://api.worldlens.co/auth/register to create your account
  2. Generate API Key: Once logged in, navigate to the API Keys section in your dashboard
  3. Copy Your Key: Save your API key securely - it won’t be shown again

​
Using API Keys

Include your API key in the request headers: 
curl -X POST "https://api.worldlens.co/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a city simulation with traffic"
  }'
Keep your API keys secure and never expose them in client-side code. Use environment variables or secure key management systems.

​
Token Authentication

For user-specific operations, you can use token authentication:

​
Getting a Token

curl -X POST "https://api.worldlens.co/auth/token/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
Response: 
{
  "token": "your_auth_token_here"
}

​
Using Tokens

Include the token in your request headers: 
curl -X GET "https://api.worldlens.co/auth/user/" \
  -H "Authorization: Token your_auth_token_here"

​
Rate Limits

API requests are subject to rate limits based on your subscription plan:
  • Free Tier: 100 requests per hour
  • Pro Tier: 1,000 requests per hour
  • Enterprise: Custom limits
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

​
Error Responses

Authentication errors return standard HTTP status codes:
Status CodeDescription
401Invalid or missing API key/token
403Insufficient permissions
429Rate limit exceeded
Example Error Response: 
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

​
Best Practices

  1. Rotate Keys Regularly: Generate new API keys periodically
  2. Use Environment Variables: Never hardcode keys in your source code
  3. Monitor Usage: Track your API usage in the dashboard
  4. Implement Retry Logic: Handle rate limits gracefully with exponential backoff