Register lookup: the registers that need a key or an agreement (GB, NL, DK, SE, EE) #1065

New issue

Open

opened 2026-10-27 16:22:13 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-27 16:22:13 +00:00

Owner

The keyed half of #1021. Register lookup shipped with the keyless registers (France, Norway, Finland, Czechia, Poland) and GLEIF, off until an administrator switches it on, with an open entry-point group for adapters (postulo.register_adapters). The registers below answer only once the operator holds a key, or an agreement with the register, so they need somewhere to keep it.

What

A settings page for the plugin. Server settings → Plugins → Register lookup → Settings (the manifest's settings, #885), holding one key or credential per register that needs one.
- Stored encrypted under POSTULO_FIELD_KEY, as a mail password or a connection's secret is (threat model rule 6), and never shown again once saved: replace or remove only.
- Who may change it follows the plugin's Access rules (#886).
The adapter contract gains a credential. An adapter says it needs one (needs_key=True, or the header or parameter it goes in); Postulo hands it to the request and never to read. An adapter that needs a key and has none is not offered, so no Look up is drawn for that country.
Adapters, each confirmed against the register's own documentation before it is written, as #1021's were (endpoint, answer, licence, with URLs and dates in the module docstring):
- GB: Companies House public data API, free key, 600 requests per 5 minutes; GET /company/{number} with HTTP Basic (the key as the user name).
- NL: KVK open dataset basisbedrijfsgegevens API, key; BV/NV only and reduced fields, 100 requests per 5 minutes.
- DK: CVR (Virk), free once access is granted; the access terms are to confirm.
- SE: Bolagsverket's free basic API (high-value datasets, 2025), key.
- EE: the e-Business Register's open data API. Every query service asks for an agreement with the RIK and a user name and password, or a REST key, free when the agreement covers only the API (introduction, read 2026-10-27). Its autocomplete service is said to need no agreement, but has no documented address or answer, so it was not used.
The rate limit stays one: POSTULO_REGISTER_LOOKUP_RATE, per account. Where a register's own limit is lower than what the instance would allow (KVK's 100 per 5 minutes), the adapter says so and the lookup refuses before asking, with the register's words.
Paperwork: each new register in the record of processing (it appears there through services() already), a line in docs/THREAT-MODEL.md for the stored keys, the Hardening table rows, and attribution per licence on the review page.

Left from #1021, small

Finland, Czechia and Poland have no link to the register's page on the review page: none was confirmed. PRH's YTJ company page and ARES's subject page are to confirm; the offline links in identifiers/registers.py would gain them too.
Poland's extract is not read for a liquidation or bankruptcy: no field for it was confirmed in the open extract (dzial6?). To confirm against a company in liquidation.
Czechia's ARES lists CZ-NACE codes with none marked as the main one, so no activity is offered; the RES source (/ekonomicke-subjekty-res/{ico}) may mark it, to confirm.

To confirm first

Carried over from #935, not settled by #1021:

Germany's "free since 2022" (handelsregister.de, per-company retrieval, no bulk);
Zefix's endpoints (Switzerland);
CVR's access terms;
OpenCorporates' free-tier limits;
Portugal's lack of an API.

#1021 (Register lookup, the keyless registers), #935 (register numbers, offline half), #885 and #886 (plugin settings and access), #913 (outbound geocoding: same rate-limit and privacy pattern).

The keyed half of #1021. *Register lookup* shipped with the keyless registers (France, Norway, Finland, Czechia, Poland) and GLEIF, off until an administrator switches it on, with an open entry-point group for adapters (`postulo.register_adapters`). The registers below answer only once the operator holds a key, or an agreement with the register, so they need somewhere to keep it. ## What - **A settings page for the plugin.** *Server settings → Plugins → Register lookup → Settings* (the manifest's `settings`, #885), holding one key or credential per register that needs one. - Stored encrypted under `POSTULO_FIELD_KEY`, as a mail password or a connection's secret is (threat model rule 6), and never shown again once saved: replace or remove only. - Who may change it follows the plugin's *Access* rules (#886). - **The adapter contract gains a credential.** An adapter says it needs one (`needs_key=True`, or the header or parameter it goes in); Postulo hands it to the request and never to `read`. An adapter that needs a key and has none is not offered, so no *Look up* is drawn for that country. - **Adapters, each confirmed against the register's own documentation before it is written**, as #1021's were (endpoint, answer, licence, with URLs and dates in the module docstring): - **GB**: Companies House public data API, free key, 600 requests per 5 minutes; `GET /company/{number}` with HTTP Basic (the key as the user name). - **NL**: KVK open dataset *basisbedrijfsgegevens* API, key; BV/NV only and reduced fields, 100 requests per 5 minutes. - **DK**: CVR (Virk), free once access is granted; the access terms are to confirm. - **SE**: Bolagsverket's free basic API (high-value datasets, 2025), key. - **EE**: the e-Business Register's open data API. Every query service asks for an agreement with the RIK and a user name and password, or a REST key, free when the agreement covers only the API ([introduction](https://avaandmed.ariregister.rik.ee/en/open-data-api/introduction-api-services), read 2026-10-27). Its *autocomplete* service is said to need no agreement, but has no documented address or answer, so it was not used. - **The rate limit stays one**: `POSTULO_REGISTER_LOOKUP_RATE`, per account. Where a register's own limit is lower than what the instance would allow (KVK's 100 per 5 minutes), the adapter says so and the lookup refuses before asking, with the register's words. - **Paperwork**: each new register in the record of processing (it appears there through `services()` already), a line in `docs/THREAT-MODEL.md` for the stored keys, the Hardening table rows, and attribution per licence on the review page. ## Left from #1021, small - Finland, Czechia and Poland have no link to the register's page on the review page: none was confirmed. PRH's YTJ company page and ARES's subject page are to confirm; the offline links in `identifiers/registers.py` would gain them too. - Poland's extract is not read for a liquidation or bankruptcy: no field for it was confirmed in the open extract (`dzial6`?). To confirm against a company in liquidation. - Czechia's ARES lists CZ-NACE codes with none marked as the main one, so no activity is offered; the *RES* source (`/ekonomicke-subjekty-res/{ico}`) may mark it, to confirm. ## To confirm first Carried over from #935, not settled by #1021: - Germany's "free since 2022" (handelsregister.de, per-company retrieval, no bulk); - Zefix's endpoints (Switzerland); - CVR's access terms; - OpenCorporates' free-tier limits; - Portugal's lack of an API. ## Related #1021 (Register lookup, the keyless registers), #935 (register numbers, offline half), #885 and #886 (plugin settings and access), #913 (outbound geocoding: same rate-limit and privacy pattern).