itworx-knowledge-hub-Public/docs/guides/service-accounts-en-automatisering.md

Service accounts en automatisering

Deze gids beschrijft scoped service accounts en tokens voor geautomatiseerde toegang tot de API. Beheerders kunnen een tijdelijk, minimaal gemachtigd importtoken via Beheer in de webapplicatie aanmaken en intrekken. De volledige levenscyclus blijft ook via de API beschikbaar voor gecontroleerde automatisering.

Wat is een service account?

Een service account is een niet-persoonlijke identiteit voor een geautomatiseerd systeem (bijvoorbeeld een CI/CD-pipeline of, in de toekomst, een MCP-server) dat via de API met het platform moet praten zonder een gewone gebruikersaanmelding te gebruiken.

• Een service account heeft één of meer tokens. Elk token heeft zijn eigen scopes (rechten), een optionele vervaldatum en kan onafhankelijk van andere tokens worden ingetrokken.
• Een token bewijst zichzelf met een Authorization: Bearer <token>-header, in plaats van een sessiecookie.
• Scopes verruimen nooit de gewone workspace-rechten — ze beperken alleen wat een reeds geauthenticeerde aanroep mag proberen. Een token met alleen knowledge:search kan nooit een pagina aanmaken, ongeacht welke rol de aanmakende beheerder zelf heeft.

Service accounts aanmaken, tonen, tokens uitgeven en intrekken kan alleen door een ingelogde beheerder (rol Eigenaar/Beheerder), via een gewone, cookie-geauthenticeerde aanroep met CSRF-bescherming — nooit door een service account zelf. Een service account kan dus nooit zijn eigen rechten verruimen of een nieuw token voor zichzelf aanmaken.

Beschikbare scopes

Scope	Betekenis
knowledge:read	Pagina's lezen
knowledge:search	Zoeken in de kennisbank
pages:read	Individuele pagina's ophalen
pages:write	Pagina's aanmaken/bewerken
projects:read	Projectdossiers en projectcontext lezen
projects:write	Projecten bewerken
project-updates:append	Een update aan een project toevoegen
decisions:read	Architectuurbeslissingen lezen
decisions:write	Architectuurbeslissingen aanmaken
runbooks:read	Runbooks lezen
runbooks:write	Runbooks aanmaken
attachments:read / attachments:write	Bijlagen lezen / uploaden
imports:read / imports:execute	Importstatus lezen / een import uitvoeren
audit:read	Audittrail lezen
system:read	Systeeminformatie lezen

Een aanvraag met een onbekende scope wordt geweigerd (HTTP 422) — er is geen manier om per ongeluk een niet-bestaande of verkeerd gespelde scope aan een token te koppelen.

Een service account aanmaken

Via de webapplicatie

1. Meld aan als beheerder en open Beheer.
2. Kies onder Serviceaccounts een van de drie vaste profielen, afhankelijk van de taak:
   • Importserviceaccount aanmaken (pagina's en bijlagen) — uitsluitend pages:read, pages:write, attachments:read en attachments:write. Voor het generieke Markdown-/bijlage-publicatietraject (tools/knowledge-ingestion/).
   • Automatiseringsserviceaccount aanmaken (infrastructuur, projecten, runbooks) — uitsluitend infrastructure:read, infrastructure:write, projects:read, projects:write, project-updates:append, runbooks:read en runbooks:write. Voor het synchroniseren van gecureerde infrastructuurfeiten (POST /inventory/curated-package), het beheren van redactionele serviceprofielen, en het publiceren van projectdossiers en runbooks.
   • Migratieserviceaccount aanmaken (LeafWiki-import) — uitsluitend imports:read en imports:execute. Voor een eenmalige, gecontroleerde LeafWiki-migratie (POST /admin/imports/preflight//execute//rollback). Deliberately gescheiden van het automatiseringsprofiel: een token voor dagelijkse infrastructuur-/projectpublicatie mag nooit ook een migratie kunnen starten.
3. Kopieer het eenmalig getoonde token onmiddellijk naar de automatisering of een geheimenbeheerder.
4. Trek het token na gebruik in via dezelfde beheerpagina.

Geen van beide vaste profielen dekt elke mogelijke automatisering — voor een taak die een andere scopecombinatie nodig heeft (bijvoorbeeld alleen zoeken, of alleen architectuurbeslissingen), gebruikt een beheerder de API hieronder met exact de benodigde scopes, nooit ruimer dan nodig.

Via de API

curl -X POST https://hub.example/api/v1/service-accounts \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: <csrf-token-van-huidige-sessie>" \
  -b cookies.txt \
  -d '{"name":"CI-bot","description":"Leest en doorzoekt de kennisbank vanuit de CI-pipeline.","scopes":["knowledge:search","pages:read"]}'

Het antwoord bevat het ruwe token exact één keer:

{
  "serviceAccountId": "…",
  "tokenId": "…",
  "rawToken": "ikh_<publieke-id>_<geheim>"
}

Bewaar dit token onmiddellijk in een geheimenbeheerder. Het platform slaat nooit de ruwe waarde op — alleen een cryptografische hash — en kan het dus nadien nooit meer tonen. Is het token kwijt, dan moet een nieuw token worden uitgegeven en het oude worden ingetrokken.

Een service account gebruiken

curl https://hub.example/api/v1/search?q=backup \
  -H "Authorization: Bearer ikh_<publieke-id>_<geheim>"

Een aanroep zonder de vereiste scope wordt geweigerd — de mutatie of leesactie vindt nooit plaats, ook al is het token op zich geldig.

Tokens roteren

Geef eerst een nieuw token uit, werk de client bij, en trek pas daarna het oude token in. Een service account is op deze manier nooit tijdelijk onbruikbaar tijdens rotatie:

curl -X POST https://hub.example/api/v1/service-accounts/<serviceAccountId>/tokens \
  -H "Content-Type: application/json" -H "X-CSRF-Token: …" -b cookies.txt \
  -d '{"scopes":["knowledge:search","pages:read"]}'

Een token intrekken

curl -X POST https://hub.example/api/v1/service-accounts/tokens/<tokenId>/revoke \
  -H "X-CSRF-Token: …" -b cookies.txt

Intrekking is onmiddellijk van kracht: de eerstvolgende aanroep met dat token wordt geweigerd, zonder wachttijd.

Herhaalde aanroepen veilig maken (Idempotency-Key)

Een aanmaak- of toevoegaanroep (bijvoorbeeld een nieuwe pagina, beslissing, runbook of projectupdate) accepteert een optionele Idempotency-Key-header. Een netwerkfout tijdens een eerdere poging kan zo veilig opnieuw worden geprobeerd zonder het risico op een dubbele pagina of dubbele update:

• Dezelfde sleutel met exact dezelfde aanvraaginhoud: het eerder gegeven antwoord wordt gewoon opnieuw teruggegeven, zonder de actie nogmaals uit te voeren.
• Dezelfde sleutel met een andere aanvraaginhoud: dit wordt geweigerd (HTTP 409) — er wordt nooit stilzwijgend iets anders uitgevoerd onder een hergebruikte sleutel.

Projectcontext voor automatisering

GET /api/v1/projects/{projectId}/context geeft een compacte, begrensde momentopname van een project (huidige stand, recente updates, actieve mijlpalen, beslissingen, runbooks, documenten) met stabiele citaten (kind, id, revisie, titel, pad, laatst bijgewerkt) in één aanroep — bedoeld voor een toekomstige MCP-server die snel projectcontext nodig heeft zonder tientallen losse aanroepen. Wanneer er meer items zijn dan het maximum, toont het antwoord expliciet truncation.truncated: true met per onderdeel het weggelaten aantal — er wordt nooit stilzwijgend informatie weggelaten zonder dat te melden.