[PR #1167] [MERGED] Store API keys in the database in hashed form #1085

New issue

Closed

opened 2026-02-26 00:30:51 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 00:30:51 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/healthchecks/healthchecks/pull/1167
Author: @cuu508
Created: 5/30/2025
Status: ✅ Merged
Merged: 6/2/2025
Merged by: @cuu508

Base: master ← Head: hashed_api_keys

📝 Commits (9)

9a8366f Store API keys in the database in hashed form
cbe282d Fix mypy warnings
b6cfaa4 Add Project.set_ping_key()
f42fdaf Add tests
fe06619 Use "." as a delimiter between key[:8] and key hash
5c435d3 Remove "Show Keys" button
552a44c Fix "create key" and "revoke" click handlers to not add "#" to URL
583e557 Update Prometheus docs
e6d96b0 Remove "show_keys" template variable

📊 Changes

14 files changed (+281 additions, -127 deletions)

View changed files

📝 hc/accounts/models.py (+51 -0)
📝 hc/accounts/tests/test_project.py (+21 -23)
📝 hc/accounts/views.py (+3 -18)
📝 hc/api/decorators.py (+47 -9)
➕ hc/api/tests/test_auth.py (+71 -0)
📝 static/css/project.css (+4 -0)
➕ static/img/docs/prometheus_api_keys.png (+0 -0)
➖ static/img/docs/prometheus_endpoint.png (+0 -0)
📝 static/img/integrations/setup_prometheus_1.png (+0 -0)
📝 static/js/project.js (+25 -15)
📝 templates/accounts/project.html (+33 -42)
📝 templates/docs/configuring_prometheus.html-fragment (+8 -6)
📝 templates/docs/configuring_prometheus.md (+10 -6)
📝 templates/integrations/add_prometheus.html (+8 -8)

📄 Description

Currently API keys are stored in in plain text in the database.

The PR implements storing future API keys in a hashed form (the existing plain text API keys still work as before).

The format of the keys presented to the user:

Read-write keys: hcw_sO9zU1olGylct7RMyUAkDaPMFHgx (prefix hcw_ followed by 28 random characters)
Read-only keys: hcr_ZJz50yB761pJ0do1YOe56Iofng76 (prefix hcr_ followed by 28 random characters)

(32 characters total)

The format of the keys stored in the database:

[first 8 plain text characters of the API key].[64 characters of HMAC of the API key]

(73 characters total)

The value stored in the database includes first 8 plaintext characters of the key for the purpose of being able to efficiently look up a project by its API key –

Project.objects.filter(api_key__startswith=key_from_client[:8])

HMAC is calculated from the full API key as presented to the user using python's hmac module:

hmac.digest(SECRET_KEY.encode(), api_key.encode(), "sha256")

Since the API keys (excluding the first 8 characters) are now stored in a hashed form, we can only show them to the user right after they are generated. The user will no longer be able to see their API keys in the Project Settings page at a later time.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/healthchecks/healthchecks/pull/1167 **Author:** [@cuu508](https://github.com/cuu508) **Created:** 5/30/2025 **Status:** ✅ Merged **Merged:** 6/2/2025 **Merged by:** [@cuu508](https://github.com/cuu508) **Base:** `master` ← **Head:** `hashed_api_keys` --- ### 📝 Commits (9) - [`9a8366f`](https://github.com/healthchecks/healthchecks/commit/9a8366f0a3bb694b94b8591206538319d70c7fcd) Store API keys in the database in hashed form - [`cbe282d`](https://github.com/healthchecks/healthchecks/commit/cbe282dc4b664f8af36394563a4d06c91ae33e2b) Fix mypy warnings - [`b6cfaa4`](https://github.com/healthchecks/healthchecks/commit/b6cfaa47d4ba034b7a836bb9fab86b332aa06a89) Add Project.set_ping_key() - [`f42fdaf`](https://github.com/healthchecks/healthchecks/commit/f42fdaff813fca0b6063833fcdcc0287102011be) Add tests - [`fe06619`](https://github.com/healthchecks/healthchecks/commit/fe066193bcc2737671ff3bbddb04c29c6579735b) Use "." as a delimiter between key[:8] and key hash - [`5c435d3`](https://github.com/healthchecks/healthchecks/commit/5c435d3aa9a2deb215c3d7927d332c9cceab01ab) Remove "Show Keys" button - [`552a44c`](https://github.com/healthchecks/healthchecks/commit/552a44c367c6898d20f94e591be67391b3583e15) Fix "create key" and "revoke" click handlers to not add "#" to URL - [`583e557`](https://github.com/healthchecks/healthchecks/commit/583e557bead3119087c611cfb5ee8063eba14ba5) Update Prometheus docs - [`e6d96b0`](https://github.com/healthchecks/healthchecks/commit/e6d96b0389b95773170a29532508caa3880f322b) Remove "show_keys" template variable ### 📊 Changes **14 files changed** (+281 additions, -127 deletions) <details> <summary>View changed files</summary> 📝 `hc/accounts/models.py` (+51 -0) 📝 `hc/accounts/tests/test_project.py` (+21 -23) 📝 `hc/accounts/views.py` (+3 -18) 📝 `hc/api/decorators.py` (+47 -9) ➕ `hc/api/tests/test_auth.py` (+71 -0) 📝 `static/css/project.css` (+4 -0) ➕ `static/img/docs/prometheus_api_keys.png` (+0 -0) ➖ `static/img/docs/prometheus_endpoint.png` (+0 -0) 📝 `static/img/integrations/setup_prometheus_1.png` (+0 -0) 📝 `static/js/project.js` (+25 -15) 📝 `templates/accounts/project.html` (+33 -42) 📝 `templates/docs/configuring_prometheus.html-fragment` (+8 -6) 📝 `templates/docs/configuring_prometheus.md` (+10 -6) 📝 `templates/integrations/add_prometheus.html` (+8 -8) </details> ### 📄 Description Currently API keys are stored in in plain text in the database. The PR implements storing future API keys in a hashed form (the existing plain text API keys still work as before). The format of the keys presented to the user: * Read-write keys: `hcw_sO9zU1olGylct7RMyUAkDaPMFHgx` (prefix `hcw_` followed by 28 random characters) * Read-only keys: `hcr_ZJz50yB761pJ0do1YOe56Iofng76` (prefix `hcr_` followed by 28 random characters) (32 characters total) The format of the keys stored in the database: ``` [first 8 plain text characters of the API key].[64 characters of HMAC of the API key] ``` (73 characters total) The value stored in the database includes first 8 plaintext characters of the key for the purpose of being able to efficiently look up a project by its API key – ``` Project.objects.filter(api_key__startswith=key_from_client[:8]) ``` HMAC is calculated from the full API key as presented to the user using python's hmac module: ``` hmac.digest(SECRET_KEY.encode(), api_key.encode(), "sha256") ``` Since the API keys (excluding the first 8 characters) are now stored in a hashed form, we can only show them to the user right after they are generated. The user will no longer be able to see their API keys in the Project Settings page at a later time. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>