Uitzoeken keys publiceren algoritmeregister

[ravimeijerrig]

Version

Use Cases

Proposal

No response

[ravimeijerrig]

Overzicht Identifiers

In de publicatiestandaard (de excel file die je kan downloaden vanaf het algoritmeregister of kan aanleveren) worden verschillende identifiers gebruikt om algoritmes uniek te identificeren:

Bron-ID

Indien van toepassing, de unieke identificatie voor deze registratie zoals door de eigenaar wordt gehanteerd. Dit is de verwijzing naar het algoritme in de interne database of het interne register van uw organisatie.

Algoritme-ID (LARS code)

Wordt automatisch toegekend door het algoritmeregister tijdens registratie via de API. Deze unieke identifier wordt gegenereerd wanneer je een nieuw algoritme aanmaakt en wordt gebruikt in alle verdere API-aanroepen.

Organisatienaam

De organisatie-identifier die door MinBZK wordt verstrekt bij het aanmaken van je account. Deze naam wordt gebruikt in de URL path van alle API-aanroepen: /organizations/{organization_name}/algorithms

Authenticatie Flow

Het proces om toegang te krijgen tot de API verloopt via:

AANMELDING (MinBZK) → WEBFORMULIER → INLOG-DOMEIN → API
       ↓                    ↓              ↓          ↓
   email +          wachtwoord       Token       LARS code
   temp password    wijzigen                     (per algoritme)
   + org_name

Overzicht Credentials

Wat je krijgt	Van waar/wanneer	Waarvoor gebruikt
E-mailadres (username)	MinBZK bij aanmelding	Inloggen op inlog-domein
Tijdelijk wachtwoord	MinBZK bij aanmelding	Eerste keer inloggen
Organisatienaam	MinBZK bij aanmelding	Verplicht in API URL path
Vast wachtwoord	Zelf instellen via webform	Inloggen op inlog-domein
Token	Inlog-domein (OAuth)	Authorization header voor API calls
LARS code	API response bij POST	Identificeert specifiek algoritme in API calls

Stapsgewijze Instructies

Stap 1: Aanmelden voor API-toegang

Stuur een email naar algoritmeregister@minbzk.nl met het verzoek om de API te mogen gebruiken voor het aanleveren van algoritmes. Vermeld hierbij:

• Voor welke organisatie je werkt
• Wie je bent (naam en functie)
• Dat je toegang wilt tot de aanlever-API

Stap 2: Ontvangen van credentials

MinBZK maakt een account voor je aan en stuurt je de volgende gegevens:

• Username: Je e-mailadres
• Tijdelijk wachtwoord: Voor eerste login
• Organisatienaam: De identifier die je nodig hebt in API-aanroepen (bijvoorbeeld "gemeente-amsterdam")

"Vervolgens wordt erachter aangegeven namens welke organisatie wordt gehandeld (bijv. …/v0_3_1/organizations/<organisatie-naam>/…). Deze namen worden verstrekt." - API handleiding

Stap 3: Instellen eigen wachtwoord

Log in op het webformulier met je tijdelijke wachtwoord en stel je eigen vaste wachtwoord in.

Zie de Handleiding webformulier voor meer details.

Stap 4: Token verkrijgen via inlog-domein

Gebruik je credentials om in te loggen bij het OAuth inlog-domein. Dit levert een bearer token op:

LOGIN_URI=https://s01.i8s.nl/realms/algreg/protocol/openid-connect/token
API_USERNAME=<jouw-email>
API_PASSWORD=<jouw-wachtwoord>

TOKEN=$(curl -d "client_id=authentication-client" \
             -d "username=$API_USERNAME" \
             -d "password=$API_PASSWORD" \
             -d "grant_type=password" \
             -d "totp=''" \
             $LOGIN_URI | jq -r .access_token)

Let op: De sessie verloopt na enkele minuten. Je moet opnieuw inloggen om een nieuw token te verkrijgen.

Stap 5: API gebruiken met token

Gebruik het verkregen token in de Authorization header van je API-aanroepen. Je hebt nu twee identifiers nodig:

1. Organisatienaam (organization_name)

• Verstrekt door MinBZK bij account aanmaken
• Gebruik in API path: /organizations/{organization_name}/algorithms
• Sla deze op in een variabele: ORGANIZATION="jouw-organisatie-naam"

2. LARS code (algorithm_id)

• Wordt automatisch gegenereerd bij het aanmaken van een algoritme
• Verkrijgen via POST request:

API_URI=https://algoritmes.overheid.nl/aanleverapi
ORGANIZATION="jouw-organisatie-naam"

LARS_CODE=$(curl -X 'POST' \
  "$API_URI/v0_3_1/organizations/$ORGANIZATION/algorithms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mijn algoritme"}' | jq -r ".lars_code")

echo "LARS code: $LARS_CODE"

De LARS code kun je vervolgens gebruiken voor alle verdere operaties op dit specifieke algoritme:

# Algoritme ophalen
curl -X 'GET' \
  "$API_URI/v0_3_1/organizations/$ORGANIZATION/algorithms/$LARS_CODE" \
  -H "Authorization: Bearer $TOKEN"

# Algoritme updaten
curl -X 'PUT' \
  "$API_URI/v0_3_1/organizations/$ORGANIZATION/algorithms/$LARS_CODE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aangepaste naam"}'

Open vragen

1. Wat zijn je rechten vanuit 1 log-in + gekoppelde organisatie_name? Aanname nu is dat we meerdere algoritmes daarvanuit kunnen publiceren, maar niet meerdere organisatie_names kunnen koppelen aan 1 log-in. Dit moeten we denk ik uitproberen.

Referenties

• API Handleiding (PDF)
• API Documentatie
• OpenAPI Specificaties Open Overheid

[github-actions]

This issue did not have any activity in the last 90 days and will be removed after 30 days