Managing API keys

Creating, renaming, and revoking keys, the ten-key limit, and why a lost key can be replaced but never recovered.

Keys live in the dashboard. There are three things you can do with one: create it, rename it, and revoke it. There is no edit, no un-revoke, and no way to read a key back after creation.

For how to send a key and what the API does with it, see authentication. This page is about the lifecycle.

Creating a key#

Give it a name and create it. The full key is returned exactly once, in that response:

hj_live_3f9a2c8e14b7d05629fa1c3e8b4d70a5162c9df83e0b7a41

That's the prefix hj_live_ plus 48 hex characters. Copy it into your secret store immediately.

The key is shown once and cannot be recovered

We store a SHA-256 hash of the key and the first 15 characters — enough to identify it in a list, not enough to reconstruct it. If you lose the key, nobody can recover it: not you, not support, not us with database access. The only fix is to revoke it and create another.

Name keys after where they run — production-api, staging, analytics-etl, giovanni-laptop. The name is the only thing distinguishing two keys in the dashboard once the secret is hidden, and "Key 1" tells you nothing on the day you need to revoke exactly one of them.

Renaming a key#

Renaming changes the label and nothing else. The key material, its usage history, and its permissions are untouched, and requests in flight don't notice. Rename freely — it's the cheapest way to keep the list honest.

Revoking a key#

Revocation takes effect on the next request. Anything using that key starts getting 401s.

Revocation is permanent

A revoked key cannot be un-revoked. There is no undo and no grace period. If you revoke the wrong key, your only path is to create a new one and deploy it — so check last_used_at in the dashboard before you revoke anything you didn't create today.

The key's usage history stays on your account after revocation, so revoking doesn't erase the record of what it did.

The ten-key limit#

You can hold 10 active keys at once. Creating an eleventh fails with a plain error telling you to revoke one first. Revoked keys don't count, so the ceiling is on live keys, not on keys you've ever had.

Ten is meant to be comfortable. If you're pressing against it, the usual cause is one key per worker — which doesn't do what people hope:

Keys don't multiply your quota. Quota and rate limit are enforced per account. Ten keys on a Growth plan share one 500,000-request monthly pool, not ten of them. Keys exist to separate environments and to be revoked independently. See your quota.

Scopes#

Every key carries a jobs:read scope. It's currently the only scope, every endpoint is readable with it, and there's nothing to configure. The field exists so write or admin scopes can arrive later without reissuing your keys.

What to do when a key gets out#

Revoke it, then rotate. Key security covers rotating without downtime and what to check afterwards.

Next#

If a key leaks

Rotation without downtime, and the browser trap.

Authentication

Headers, the query fallback, and verifying a key.

Was this page helpful?