API-referentie

Alle endpoints van de BeID auth-backend. Sessie-endpoints gebruiken een veilige cookie; server-naar-server-endpoints gebruiken een API-sleutel (Authorization: Bearer beid_sk_…).

Basis-URL

Productie: https://id.becyber.nl · Lokaal: http://localhost:4000

Authenticatie

POST/v1/auth/register

Maak een account aan en start een sessie. Body: name, email, password.

POST/v1/auth/login

POST/v1/auth/logoutsessie

Beëindig de huidige sessie.

GET/v1/auth/mesessie

Gegevens van de ingelogde gebruiker.

E-mailverificatie & wachtwoordherstel

POST/v1/auth/email/send-verificationsessie

Stuur (opnieuw) een verificatiemail naar de ingelogde gebruiker.

POST/v1/auth/email/verify

Bevestig een e-mailadres. Body: token (uit de e-maillink).

POST/v1/auth/password/forgot

Vraag een herstellink aan. Body: email. Antwoordt altijd gelijk (anti-enumeratie).

POST/v1/auth/password/reset

Stel een nieuw wachtwoord in. Body: token, password. Trekt alle bestaande sessies in.

Voorbeeld — registreren

curl -X POST https://id.becyber.nl/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Jan Jansen","email":"jan@bedrijf.nl","password":"EenSterkWachtwoord1"}'

Multi-factor (MFA)

POST/v1/auth/mfa/enrollsessie

Genereer een TOTP-secret + QR-code. MFA wordt pas actief na /activate.

POST/v1/auth/mfa/activatesessie

Bevestig met een code uit je authenticator. Body: token.

POST/v1/auth/mfa/disablesessie

Zet MFA uit (vereist een geldige actuele code).

Identiteitsverificatie (KYC)

POST/v1/kyc/sessionssessie

Start een verificatie. Body: documentType (passport · id_card · drivers_license), documentCountry (ISO 3166-1, bijv. NL).

POST/v1/kyc/sessions/:id/documentsessie

Upload een identiteitsdocument (multipart, JPG/PNG/WEBP/PDF, max 8 MB). Wordt versleuteld opgeslagen (AES-256-GCM); zet de status op in_review.

GET/v1/kyc/statussessie

De KYC-status van de ingelogde gebruiker.

GET/v1/verifications/:userIdAPI-sleutel

Server-naar-server: controleer de verificatiestatus van een gebruiker.

Beoordelaarsconsole (rol: reviewer/admin)

GET/v1/admin/kycreviewer

Openstaande verificaties (pending / in review).

GET/v1/admin/kyc/:id/documentreviewer

Stream het ontsleutelde document (nooit ontsleuteld opgeslagen).

POST/v1/admin/kyc/:id/decisionreviewer

Keur goed of af. Body: decision (approve / reject), optioneel note.

Passkeys (WebAuthn)

POST/v1/auth/passkeys/register/optionssessie

Start registratie; geeft de WebAuthn-opties voor de browser.

POST/v1/auth/passkeys/register/verifysessie

Verifieer en sla de nieuwe passkey op.

POST/v1/auth/passkeys/login/options

Start passwordless inloggen. Body: optioneel email.

POST/v1/auth/passkeys/login/verify

Verifieer de passkey-assertion en start een sessie.

SAML 2.0 (IdP)

GET/saml/metadata

IdP-metadata voor je service provider.

GET/saml/ssosessie

SSO-endpoint (HTTP-Redirect en HTTP-POST binding). Retourneert een ondertekende SAML-assertion naar de ACS van de SP.

Voorbeeld — verificatie ophalen (server-naar-server)

curl https://id.becyber.nl/v1/verifications/USER_ID \
  -H "Authorization: Bearer beid_sk_xxx"

200 OK

{
  "userId": "cmpv...",
  "kycLevel": "verified",
  "kycStatus": "approved",
  "emailVerified": true
}

Ontwikkelaarsplatform

GET/v1/developer/clientssessie

Lijst van je OAuth-clients.

POST/v1/developer/clientssessie

Maak een OAuth-client. Body: name, redirectUris[]. Geeft clientId + clientSecret (eenmalig).

GET/v1/developer/api-keyssessie

Lijst van je API-sleutels (zonder de geheime waarde).

POST/v1/developer/api-keyssessie

Maak een API-sleutel. De waarde beid_sk_… wordt eenmalig getoond.

DELETE/v1/developer/api-keys/:idsessie

Trek een API-sleutel in.

Foutformaat

Alle fouten volgen hetzelfde formaat:

Fout

{
  "error": "validation_error",
  "message": "Controleer de ingevoerde gegevens",
  "details": { "password": ["Wachtwoord moet minimaal 12 tekens zijn"] }
}

Status	Betekenis
`401`	Niet (juist) geauthenticeerd
`403`	Geen toegang
`409`	Conflict (bijv. e-mail al in gebruik)
`422`	Validatiefout (zie `details`)
`429`	Te veel verzoeken (rate limit)