Authentication

Authenticate with an API key in the X-Api-Key header. Covers key format, limits, rotation, and the one endpoint that needs no key.

Every request except one carries your key in the X-Api-Key header.

curl "https://connect.jobo.world/api/jobs?q=engineer&page_size=5" \
  -H "X-Api-Key: $JOBO_API_KEY"

from jobo_enterprise import JoboClient

with JoboClient(api_key="YOUR_API_KEY") as client:
    results = client.search.search(q="engineer", page_size=5)

1. Create a key

   Sign in to the dashboard and go to Settings → API Keys. The full key is shown once, at creation — store it immediately.

2. Send it as a header on every request

   Query-parameter authentication is not supported, and there is no Authorization: Bearer form.

3. Use HTTPS

   Plain HTTP is answered with a 301 redirect and never reaches the API. Most HTTP clients silently downgrade a redirected POST to GET and drop the body, so always call https:// directly.

---

Base URL

https://connect.jobo.world

Every path in these docs is relative to it. jobs-api.jobo.world resolves to the same service and appears in some older client configuration, but connect.jobo.world is canonical — prefer it in new integrations.

There is a single production host. There is no separate sandbox or staging environment, and no test-mode key: every issued key is a live key. For developing without spending, see free endpoints.

---

Key format and scope

Keys look like this:

jbe_live_XXXXXXXXXXXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The jbe_live_ prefix is recognised by secret scanners such as GitHub’s, so a leaked key gets flagged.

A key is scoped to your account. There is no organisation or team concept, and — importantly — keys have no scopes or per-endpoint permissions. Any key can call any endpoint your plan allows; what varies is your rate-limit group and wallet balance. Creating a key “for search only” is not possible.

You can hold at most 5 active keys at a time. Creating a sixth returns 409 Conflict — revoke or let one expire first.

---

The one endpoint that needs no key

GET /api/companies/{id} is anonymous. It takes no key, costs nothing, is not rate limited, and is CDN-cached. This exists so the details_url on any job resolves from a browser or a public page without exposing a credential.

curl "https://connect.jobo.world/api/companies/{company_id}"

Everything else — including GET /api/companies/{id}/jobs — requires a key.

---

Rotating a key

1. Create the replacement

   Multiple keys are valid simultaneously, so there is no gap in access.

2. Deploy it

   Roll the new key out to every service.

3. Revoke the old one

   Once no traffic uses it.

If you are already at the 5-key limit, you cannot create the replacement first — you must revoke something before creating, which does break the overlap. Keep a spare slot free if you rotate on a schedule.

Revocation takes effect within roughly 30 seconds, not instantly: successful authentications are briefly cached. Treat a revoked key as live for that window, and if a key is genuinely compromised, revoke it and contact [e-mail].

---

Storing keys safely

Never put a key in client-side code, a public repository, or a browser request. All calls should originate from your backend.

• Read keys from environment variables or a secrets manager, never from source.
• Use a separate key per environment and per service, so you can revoke narrowly. Remember the limit of 5.
• Watch usage in the dashboard for unexpected spikes.

export JOBO_API_KEY="your_api_key_here"     # macOS / Linux

---

When authentication fails

A missing or unusable key returns 401 with WWW-Authenticate: ApiKey realm="api.jobo.world":

{ "error": "Missing X-Api-Key header" }

{ "error": "Invalid or expired API key" }

Note that a valid key with an insufficient plan or an empty wallet returns 402, not 403. See Errors for every envelope, and Response headers for what accompanies a successful response.

401 on every request

• Confirm the key is an HTTP header named X-Api-Key, not a query parameter.
• Check for a trailing newline or space in the value — a common result of reading the key from a file.
• Verify the key is still active under Settings → API Keys.
• Confirm you are calling https://connect.jobo.world, not the dashboard host.

Works in curl, fails in my application

• Some HTTP clients and proxies strip unknown custom headers — check that X-Api-Key survives to the wire.
• Confirm HTTPS, not HTTP; a redirect will drop your request body.
• If you recently rotated, make sure the deployed key is the new one.

I got a 409 creating a key

You already have 5 active keys. Revoke one, or wait for one to expire, then retry.

My key stopped working right after I revoked a different one

Revoking is per-key and does not affect other keys. Confirm which key your service is actually loading — most reports of this turn out to be a stale environment variable or a cached deployment config.