Skip to main content

​
API Key Authentication

All API requests require authentication via the X-Api-Key HTTP header. Keys are scoped to your organisation and grant access to every endpoint your plan permits. 
curl https://connect.jobo.world/api/jobs \
  -H "X-Api-Key: YOUR_API_KEY"
1

Get your API key

Sign in to the Jobo Enterprise Dashboard and navigate to Settings → API Keys. You can create multiple keys — one per environment or service — and revoke any key at any time.
2

Add the header to every request

Include X-Api-Key: YOUR_API_KEY in every request. The key must be sent as an HTTP header — query-parameter authentication is not supported.
3

Use HTTPS only

All requests must use HTTPS. Plain HTTP requests are rejected with a 301 redirect, and the request body is never processed.

​
Base URL

https://connect.jobo.world
All paths in this documentation are relative to this base URL.

​
Environments

Jobo Enterprise exposes two environments that share the same authentication mechanism but differ in data access and billing.
EnvironmentBase URLPurpose
Productionhttps://connect.jobo.worldLive job data, production credits deducted
Test / Sandboxhttps://sandbox.connect.jobo.worldSynthetic data, no credit charges, same API surface
Use the sandbox for integration testing and CI pipelines to avoid consuming production credits.

​
SDK Authentication

Pass your API key when you instantiate the client — the SDK handles the header for every subsequent call. 
from jobo_enterprise import JoboClient

client = JoboClient(api_key="YOUR_API_KEY")

# All subsequent calls are authenticated automatically
results = client.jobs.search(q="data engineer", page_size=5)
Store your API key in an environment variable (e.g. JOBO_API_KEY) and read it at runtime instead of hard-coding it.

​
Response Headers

Every successful API response includes headers that help you monitor your usage and stay within limits.

​
Credit Headers

Credits are deducted per request based on the endpoint and plan. These headers are present on every 2xx response:
HeaderTypeDescription
X-Credits-UsedintegerNumber of credits consumed by this request
X-Credits-RemainingintegerCredits remaining in your current billing period

​
Rate-Limit Headers

Rate limits are applied per API key. When you approach or exceed your limit, use these headers to implement backoff:
HeaderTypeDescription
X-RateLimit-LimitintegerMaximum requests allowed per window
X-RateLimit-RemainingintegerRequests remaining in the current window
X-RateLimit-ResetintegerUnix epoch timestamp when the window resets
When X-RateLimit-Remaining reaches 0, subsequent requests return 429 Too Many Requests. Wait until the X-RateLimit-Reset timestamp before retrying.

​
Security Best Practices

Never expose your API key in client-side code, public repositories, or browser requests. Always make API calls from your backend server.
  • Store API keys in environment variables or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault)
  • Rotate keys periodically from the dashboard — revoked keys are rejected immediately
  • Use separate keys for development, staging, and production
  • Monitor usage in the dashboard to detect anomalies and unexpected spikes
  • Apply the principle of least privilege — only create keys that your service actually needs

​
Error Responses

​
401 Unauthorized — Missing or Invalid Key

If your API key is missing, malformed, or revoked, you’ll receive: 
{
  "status": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

​
403 Forbidden — Insufficient Permissions

If your key is valid but your plan does not include the requested endpoint: 
{
  "status": 403,
  "error": "Forbidden",
  "message": "Your plan does not include access to this endpoint"
}

​
429 Too Many Requests — Rate Limit Exceeded

If you exceed your per-key rate limit: 
{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 1677721600",
  "retryAfter": 1677721600
}

​
Troubleshooting

  • Confirm you’re sending the key as an HTTP header (X-Api-Key), not as a query parameter.
  • Check for trailing whitespace or newline characters in the key value.
  • Verify the key has not been revoked in Settings → API Keys.
  • Make sure you’re using the correct key for the target environment (production vs. sandbox).
  • Ensure your HTTP client is not stripping custom headers — some frameworks require explicit allow-listing.
  • Double-check that you’re using HTTPS, not HTTP.
  • If you’re behind a corporate proxy, confirm it forwards the X-Api-Key header untouched.
  • Read the X-RateLimit-Reset header and wait until that timestamp before retrying.
  • Implement exponential backoff with jitter in your retry logic.
  • If you consistently hit limits, consider upgrading your plan or contacting support for a rate-limit increase.
  • Each endpoint has a different credit cost — check the Pricing page for the cost table.
  • Use the sandbox environment (sandbox.connect.jobo.world) for testing — sandbox calls are free.
  • Review the X-Credits-Used header on each response to audit consumption per endpoint.
  1. Create a new key in the dashboard.
  2. Deploy the new key to your services.
  3. Once all traffic uses the new key, revoke the old one.
Both keys are valid simultaneously, so there is no gap in access.

​
Need Help?

WhatsApp Support

Chat with our team for fast, real-time assistance.

Email Support

Reach us at support@jobo.world for account or billing queries.