Get started / Authentication

Authentication

API keys, how to send them, and how to keep them out of places they shouldn't be.

Every endpoint except /v1/health requires an API key.

Getting a key#

Keys are created in the dashboard. A key looks like:

hj_live_3f9a2c8e14b7d05629fa1c3e8b4d70a5162c9df83e0b7a41

That's the prefix hj_live_ plus 48 hex characters (24 random bytes).

The key is shown once

Only a SHA-256 hash of your key is stored. The full value crosses the wire exactly once, at creation, and cannot be recovered afterwards — not by you, not by support. Copy it into your secret store immediately. If you lose it, revoke it and create another; revocation takes effect on the next request.

You can hold up to 10 active keys at a time. Revoked keys don't count against that limit.

Sending the key#

Two ways, in precedence order.

BASH
curl -H "Authorization: Bearer $HYPERJOBS_KEY" \
  "https://api.hyperjobs.io/v1/jobs?limit=1"

Use this everywhere you can. The key stays out of URLs, which means it stays out of proxy logs, browser history, and Referer headers.

If both are present, the header wins.

The Bearer prefix is optional — the server strips it if present and otherwise treats the whole header value as the key. Authorization: hj_live_… works. Send Bearer anyway; it's what every HTTP client and proxy expects.

Calling from a browser#

Don't ship a key to the browser — but the mechanics work now.

Every response carries Access-Control-Allow-Origin: *, and the API answers the OPTIONS preflight (204, with Authorization in Access-Control-Allow-Headers), so a fetch with an Authorization header works from page JavaScript. Use the header in a browser like anywhere else — ?api_key= still works but puts the key in every log along the way.

A browser-side key is a public key

Anything in browser JavaScript is readable by anyone who opens devtools. A key shipped to the browser is a key you have published, and it carries your whole quota. Call the API from your server and expose your own endpoint to your frontend.

Verifying a key#

/v1/health is unauthenticated, so it can't confirm a key. The cheapest authenticated check is a one-row query:

BASH
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  "https://api.hyperjobs.io/v1/jobs?limit=1"

200 means the key is live. 401 means it's missing, malformed, unknown, or revoked — the response doesn't distinguish, deliberately:

JSON
{
  "error": "invalid or missing api key",
  "hint": "Authorization: Bearer <key>"
}

Scopes#

Keys carry a jobs:read scope. It is currently the only scope, and every endpoint is readable with it — there is nothing to configure. The field exists so that write or admin scopes can be added later without reissuing keys.

Rotating#

There's no automatic rotation. To rotate without downtime:

  1. Create the new key

    You can hold 10 active keys, so the old one keeps working while you roll.

  2. Deploy it

    Update your secret store and let the change propagate everywhere.

  3. Confirm the old key is idle

    The dashboard shows last_used_at per key. Wait until the old key stops moving.

  4. Revoke the old key

    Revocation is immediate and permanent. The key's usage history is retained for your billing records.

Next#

Rate limits & quotas

What a key is allowed to do.

Errors

Every status code the API returns.

Was this page helpful?