Add the authenticated Lovdata API surface in a later release

[MariusStorhaug]

The first release of the module covers what Lovdata publishes openly: the NLOD 2.0 data packages and the service endpoints, all of which work with no account. Everything else Lovdata offers through its API — search, document retrieval, structured rules, vocabularies, reference resolution — sits behind an API key issued to holders of the api role, and is out of reach from PowerShell until the module can authenticate.

Request

Desired capability

A user who has a Lovdata API key wants the same experience for the paid surface as for the open one: store the key once, then call commands that return objects. The key must be encrypted at rest and never appear in output, and more than one key must be able to coexist so a script can move between accounts or environments.

This is a milestone rather than a single command. It covers the credential store, the authenticated transport path, and the command groups that depend on them, each of which is tracked in its own issue.

Acceptance criteria

• An API key can be stored, inspected, replaced, and removed without ever being displayed in clear text
• Several named credentials can coexist, with one of them as the default that commands fall back to
• Commands that need a key produce a clear, actionable message when none is stored, rather than a raw HTTP failure
• Commands that do not need a key keep working with none stored, exactly as they do in the first release
• The test suite still passes with no API key available, so contributors and forks are not blocked

What is in scope

Every operation the OpenAPI document marks with the X-API-Key security requirement. As of writing that is 26 operations across these areas:

Area	Endpoints
Account	/v1/userinfo
Search	/v1/search
Documents	/documentMeta, /documentIndex, /documentHistory, /v1/download/document, /v1/documentPartChanges
Legal sources	/v1/legalSource/list, /listBase, /baseHistory
Structured rules	/v1/structuredRules/list, /v1/structuredRules/list/{base}, /v1/structuredRules/get/{base}/{ruleFile}, /v1/structuredRules/get/{base}/{ruleFile}/{date}, /v1/structuredRules/timeline/{base}/{ruleFile}
Vocabularies	/vocabulary/legalAreas, /vocabulary/legalSources
References	/lookup, /genref, /renderRefID
AI	/v1/ai/strategySearch, /v1/ai/generateResponse, /v2/ai/selectionList/generateResponse
Upload	/v1/upload/{baseName}

References

• Keys are issued by Lovdata to users holding the api role; contact api@lovdata.no
• Authentication accepts either the X-API-Key header or HTTP Basic, per the API introduction
• Lovdata Pro is the commercial offering the paid surface belongs to
• About the API service draws the line between the open site and Pro

---

Technical decisions

Milestone shape: This issue is the parent. The credential store lands first, then each command group as its own pull request, the same way the open surface was built. The child issues already filed stay where they are and are linked from here rather than restated.

Credential store: Context, consistent with PSModule/GitHub and PSModule/Domeneshop. Per-user contexts hold the key in the PSModule.Lovdata vault; the module-scoped settings context already used for ApiBaseUri gains the default-context pointer. An implementation of exactly this was written and reviewed during the bootstrap, then removed when the first release was scoped to the open surface — recover it from the history of build-lovdata-module rather than writing it again.

Transport: The existing private transport helper gains optional key injection. It must stay usable without a key so the open commands are unaffected, so the authenticated path is an addition to one helper rather than a second transport.

Authentication scheme: X-API-Key only. Basic authentication is also accepted by the service but adds a second credential shape for no user-visible benefit; revisit only if a concrete need appears.

Versioning: The credential store and the first authenticated command are additive, so a minor bump. Nothing here breaks the open surface.

Open: whether the AI endpoints belong in this module at all, or in a separate one. They are a different kind of capability from retrieving legal text and carry their own cost model. Decide before planning that group.

---

Implementation plan

Child issues, in the order they are expected to land:

• Credential store and authenticated transport — to be filed once this milestone starts, recovering the implementation from the build-lovdata-module history
• Add legal area and legal source vocabulary commands #10 — legal source and legal area vocabularies
• Add full-text search across Lovdata legal sources #5 — full-text search
• Add document metadata and content retrieval commands #6 — document metadata and content retrieval
• Add structured rule retrieval and version timeline commands #7 — structured rules and version timelines
• Retry rate-limited and transient Lovdata API responses #12 — rate-limit and transient-failure retry
• Verify the open API surface with live contract tests that need no credentials #13 — live integration tests behind a repository secret
• Reference resolution — /lookup, /genref, /renderRefID, to be filed
• Account information — /v1/userinfo, folded into the credential store work

Not planned here: /v1/upload/{baseName}, which is for organisations publishing into Lovdata rather than reading from it, and the AI endpoints pending the decision above.