⚡️ API keys.

What is an API key and why do you need one

An API key is a unique string that allows third-party applications or scripts to access your Headframe account data and perform actions on its behalf — without manually logging in through a browser.

Previously, keys were only issued by contacting support. Now you can create and manage them yourself directly in your account — with full control over who gets access to what.

Typical use cases:

• Automating hashrate and worker monitoring
• Integrating with external dashboards and analytics systems
• Managing client accounts from your own interface
• Working with multiple accounts through a single script

Access levels

When creating a key, you choose one of four access levels.

Viewer – Read-only: view statistics, workers, hashrate
Accountant – View financial information: accruals and payouts
Treasurer – Access to hub financial operations, including miner data
Administrator – Full access: manage settings, workers, and clients

Principle of least privilege
Grant a key only as much access as the task requires. If an integration only reads statistics — choose Observer, not Administrator.

Scope

In addition to the access level, you choose which entities the key applies to: miners, operators (hubs), or pools.

You only see the entities available to your account. If you have no operators, that section simply won't appear.

"Select all" — what it means

Checking "Select all" means the key will automatically apply to all current and future entities. For example, if you add a new miner later — the key will automatically gain access to it.

If you select entities manually, the key will only work for those chosen at creation. New entities won't be added automatically.

How to create a key

The section is located at: Account → Access → API Keys.

1. Enter a key name — this is a required field. The name helps identify what the key is for (e.g.  monitoring-bot ,  dashboard-readonly ).
2. Select an access level from the dropdown.
3. Check the entities the key should apply to, or click "Select all".
4. Click "Create key" and confirm the action via two-factor authentication.
5. Copy and save the key. It is shown in full only once. After closing the dialog, it cannot be recovered.

⚠️ The key is shown only once
After creation, the key is displayed in full only at the moment of generation. Save it somewhere safe: a password manager, environment variables, or CI/CD secrets. The key is stored in encrypted form only on the creator's side. The pool and support do not store data about created keys.

Key list

After creation, the key appears in the API Keys table. It shows:

• Name and masked value — the prefix and the next six characters for identification
• Entity — which objects the key is linked to
• Access level
• Revoke button (trash icon)

⚠️ The full key value is never stored or displayed — not in the interface, not by the Headframe team.

How to revoke a key

If a key is compromised, accidentally published in a public repository, or simply no longer needed — revoke it.

1. Find the key in the list and click the trash icon on the right.

2. Confirm the action via two-factor authentication.

3. The key is immediately deactivated. All services using it will lose API access.

Revoked keys move to the "Revoked keys" section, which appears below the main list. The name, scope, and access level of the revoked key are preserved there, but it cannot be deleted again or restored.

⚠️  This action is irreversible.If you need a new key with the same permissions — simply create one.

What to do if a key is lost

If you didn't save the key after creation — it cannot be recovered. This is by design: the full key value is never stored anywhere.

The correct flow:

1. Revoke the old key (or leave it — it will keep working until you delete it).
2. Create a new key with the required settings.
3. Update the key everywhere it is used.

You don't have to delete the old key right away — it will continue working in parallel while you transition to the new one.

Документация 

https://developers.headframe.io/

FAQ

How many keys can I create? 
There is no limit. Create as many keys as you need — with different access levels and scopes for different tasks.

Do keys issued through support still work?
Yes, old keys continue to work. However, they are not shown in the interface and do not update automatically when new entities are added. If you want full control over your keys — create new ones through the Access section.

Is two-factor authentication required for working with keys?
Yes — both creating and revoking a key require confirmation via 2FA.

Can I change the permissions of an existing key?
No. The access level and scope are set at creation and cannot be changed. If you need different permissions — revoke the old key and create a new one.

Can support see my keys?
No. Keys are stored in hashed form. Neither the Headframe team nor support can see the full value of your key.