Wat het is
De SAW API zoekt persoonsgegevens in tekst en documenten en vervangt ze door plaatshouders. Zo stelt uw software een vraag aan een externe taalmodeldienst zonder de echte waarden mee te sturen, en zet ze het antwoord daarna lokaal terug.
Het is dezelfde detectie-engine als in de Safe AI Way-browserextensie, met dezelfde Belgische identificatoren (INSZ, KBO, btw-nummer, IBAN met controlesom) en dezelfde Belgische namenlijst. Het pakket bestaat uit drie delen:
- Een stateless HTTP-dienst die per tekst teruggeeft waar persoonsgegevens staan (type en positie) en een gemaskeerde versie van de tekst. Ook voor documenten:
.docx,.xlsx,.csv,.tsv,.txt,.mden pdf met tekstlaag. - Een SDK in TypeScript die die posities omzet naar consistente plaatshouders zoals
[[PERSON_1_K3F9Q]], de koppeling tussen plaatshouder en echte waarde alleen bij u bijhoudt, en het antwoord van de LLM terugzet. Node 20 of hoger, Deno of Bun. - Een taalonafhankelijke specificatie van die pseudonimisering met conformiteitsvectoren, plus een Python-referentie, zodat u ook in Python, Java of .NET kunt integreren.
Geen publiek endpoint: elke aanroep vraagt een sleutel, en een sleutel bestaat alleen onder een overeenkomst. Geen anonimisering: gepseudonimiseerde tekst blijft voor u persoonsgegevens, want u hebt de koppeling. Geen garantie dat alles gevonden wordt: een gemiste detectie gaat ongemaskeerd naar de LLM. En geen juridisch advies.
Hoe het werkt
Een rondreis bestaat uit vier stappen. Alleen de eerste stap raakt de SAW API; de koppeling tussen plaatshouder en echte waarde ziet de dienst nooit.
- SAW APIAnalyse
De dienst geeft per tekst de posities en types van de persoonsgegevens terug. Er wordt niets bewaard.
Jan Peeters (85.07.30-033.28) - SDK, in uw procesPlaatshouders
De SDK nummert elke verschillende waarde consistent en houdt de koppeling in het geheugen van uw proces.
[[PERSON_1_K3F9Q]] ([[NATIONAL_ID_1_K3F9Q]]) - LLM naar keuzeTaalmodel
Alleen de gepseudonimiseerde tekst gaat naar de LLM die u kiest. Het antwoord bevat dezelfde plaatshouders.
Beste [[PERSON_1_K3F9Q]], ... - SDK, in uw procesHerstel
De SDK zet lokaal de echte waarden terug, alleen voor de plaatshouders die in deze beurt naar de LLM gingen.
Beste Jan Peeters, ...
De koppeling blijft lokaal. De server kent geen restore- of pseudonymize-endpoint en ziet de koppeling tussen plaatshouder en waarde nooit. Wilt u een gesprek over meerdere aanvragen voortzetten, dan bewaart u de sessie zelf, versleuteld met een sleutel uit uw eigen sleutelbeheer.
De plaatshouders overleven de opmaak van het taalmodel. De SDK zet ook plaatshouders terug die het taalmodel licht heeft aangepast, en laat zich niet misleiden door nagemaakte plaatshouders.
Wat er herkend wordt
De API spreekt een stabiele, publieke woordenschat van types. Binnen versie 1 verandert die lijst alleen door toevoeging.
| Type | Wat het dekt |
|---|---|
PERSON | persoonsnamen |
EMPLOYEE_NUMBER | personeelsnummer (alleen herkend als tabelkolom) |
EMAIL | e-mailadressen |
PHONE | telefoonnummers |
IBAN | IBAN, ook het oude Belgische rekeningnummer |
CARD | betaalkaartnummers (met Luhn-controle) |
NATIONAL_ID | rijksregisternummer (INSZ) en andere nationale nummers |
ADDRESS | straat, gemeente, adres |
DATE_OF_BIRTH_AGE | geboortedatum en leeftijd |
CHILD | vermeldingen van kinderen en gezinslast |
HEALTH | gezondheidsgegevens |
TRADE_UNION | vakbondslidmaatschap |
CASE_NUMBER | rolnummers en dossiernummers van rechtbanken |
VAT_NUMBER | btw-nummers |
COMPANY_NUMBER | ondernemingsnummer (KBO) en RSZ-werkgeversnummer |
AMOUNT | bedragen met een munteenheid (€, EUR, euro, £, USD, GBP; $ alleen ervoor) |
Daarbovenop geeft u per aanvraag eigen termen mee: de namen van de betrokkenen, een bedrijfsnaam of een interne dossiercode. Elke API-sleutel heeft bovendien een minimum aan maskering dat een aanroeper niet kan verlagen.
Volledigheid
Geen enkele detectie is volledig. Met eigen termen per dossier vangt u wat de engine niet kent, en in de pilot meet u de detectie op uw eigen teksten.
Twee leveringsvormen
U draait de dienst als container in uw eigen infrastructuur. De inhoud verlaat uw netwerk niet.
- Wat verlaat uw netwerk
- Alleen gebruikstellingen die u zelf exporteert; geen inhoud.
- Rol van Safe AI Way
- Geen rol voor de inhoud: wij leveren software onder een licentieovereenkomst.
- Voorwaarde
- Een licentie van Safe AI Way; zonder geldige licentie start de container niet.
Pilot op aanvraag
Wij draaien de dienst in de EU. De tekst wordt in het geheugen verwerkt en niet bewaard.
- Wat verlaat uw netwerk
- De tekst gaat naar onze dienst, alleen voor de duur van de aanvraag.
- Rol van Safe AI Way
- Verwerker of subverwerker, uitsluitend met een verwerkersovereenkomst.
- Voorwaarde
- Beschikbaar na de pilotfase.
Na de pilotfase
Zo bouwt u het in
Er zijn twee delen die samenwerken. De dienst doet de detectie: ze draait bij ons in de EU, of als container in uw eigen infrastructuur. De SDK draait in uw backend: ze vult de plaatshouders in, houdt de koppeling bij en zet het antwoord terug. De SDK gebruikt u altijd; voor de dienst kiest u gehost of self-hosted.
Toont vraag en antwoord. Geen API-sleutel, geen koppeling.
API-sleutel uit uw kluis. De koppeling tussen plaatshouder en echte waarde blijft hier.
Vindt de persoonsgegevens en bewaart geen inhoud.
OpenAI, Anthropic, Mistral of een eigen model. Ziet nooit de echte waarden.
Vooraf: u krijgt van ons een API-sleutel per organisatie, onder contract. Uw backend leest die uit een kluis.
- Vraag. Uw webapp stuurt de vraag van de gebruiker naar uw eigen backend.
- Analyse. Uw backend stuurt de tekst of het document via de SDK naar de SAW-dienst.
- Posities terug. De dienst geeft de plaats en het type van elk persoonsgegeven terug. De SDK vervangt ze door plaatshouders en houdt de koppeling in het geheugen van uw proces.
- Taalmodel. Uw backend stuurt alleen de gepseudonimiseerde tekst naar het taalmodel van uw keuze, met uw eigen sleutel.
- Antwoord met plaatshouders. Het taalmodel antwoordt met dezelfde plaatshouders.
- Herstel. De SDK zet de echte waarden terug, en uw backend stuurt het antwoord naar uw webapp.
Self-hosted is één stap extra. U start onze container met het licentiebestand dat u van ons krijgt en laat de SDK naar die interne URL wijzen. De rest van de integratie blijft gelijk.
Waarom niet rechtstreeks vanuit de webapp? In een browser is de API-sleutel leesbaar voor elke gebruiker, en de koppeling bevat de echte waarden. Beide horen in uw backend, net zoals uw eigen LLM-sleutel. De dienst weigert daarom elke aanvraag die uit een browser komt.
Codevoorbeeld
Een rondreis in TypeScript, overgenomen uit de snelstart van de documentatie. Ter illustratie: de SDK (@safeaiway/sdk) staat nog niet publiek op npm; u ontvangt hem bij de pilot. Alle voorbeelden gebruiken fictieve gegevens.
import { SawClient, Session } from "@safeaiway/sdk";
// Uw eigen LLM-aanroep (OpenAI, Anthropic, Mistral, ...): krijgt berichten, geeft het antwoord.
export type Llm = (berichten: readonly string[]) => Promise<string>;
const SYSTEEMPROMPT =
"Sommige gegevens zijn vervangen door plaatshouders in de vorm [[TYPE_NUMMER_CODE]]. " +
"Neem plaatshouders letterlijk en ongewijzigd over. Verzin geen nieuwe plaatshouders.";
export async function vraagZonderPersoonsgegevens(vraag: string, llm: Llm): Promise<string> {
const client = new SawClient({
apiKey: process.env.SAW_API_KEY!, // saw_<kid>_<geheim>, uit een kluis; nooit in een browser
baseUrl: process.env.SAW_API_URL!, // het adres van uw container
});
// Eén sessie per dossier en per lezer. De mapping blijft in dit proces.
const session = Session.create();
const turn = await session.pseudonymizeWith(client, { input: [vraag] });
// Naar de LLM gaan alleen plaatshouders zoals [[PERSON_1_K3F9Q]], nooit de echte waarden.
const antwoord = await llm([SYSTEEMPROMPT, ...turn.texts]);
// Lokaal terugzetten, VOOR het weergeven. Alleen plaatshouders van deze beurt komen terug.
const { text } = await session.restore(antwoord, { allow: turn });
return text;
}
Zonder SDK spreekt u de dienst rechtstreeks aan. Een analyseaanroep met curl, tegen een self-hosted container:
curl -sS https://saw.intern.voorbeeld/v1/text/analyze \
-H "Authorization: Bearer $SAW_API_KEY" \
-H "Content-Type: application/json" \
--data '{"items":[{"id":"msg-1","text":"Jan Peeters (85.07.30-033.28) vraagt zijn loonfiche."}]}'
{
"items": [
{
"id": "msg-1",
"masked_text": "[[PERSON]] ([[NATIONAL_ID]]) vraagt zijn loonfiche.",
"entities": [
{ "entity": "PERSON", "start": 0, "end": 11, ... },
{ "entity": "NATIONAL_ID", "start": 13, "end": 28, ... }
],
"counts": { "PERSON": 1, "NATIONAL_ID": 1 }
}
],
"usage": { "characters": 52, "items": 1 }
}
Het antwoord bevat geen koppeling, alleen posities en de gemaskeerde tekst. Voor een rondreis met nummering en terugzetten gebruikt u de SDK, of implementeert u de specificatie zelf. Behandel elk antwoord als persoonsgegevens en log het niet. Op aanvraag ontvangt u ook de Python-referentie-implementatie (Python 3.9 of hoger) en de OpenAPI-specificatie van de dienst.
Integratiepatronen
Eén sessie per dossier en per lezer. Pseudonimiseer de vraag, stuur alleen plaatshouders naar de LLM, en zet het antwoord terug vóór u het rendert. Ook een gestreamd antwoord zet de SDK stukje per stukje terug.
Een document gaat in één aanvraag naar /v1/documents/analyze: een .xlsx per cel, een pdf per pagina, een .docx als tekst. Tekst gaat met tot 100 items per aanvraag; één ongeldig item laat de hele aanvraag falen, er wordt nooit een halve batch verwerkt of gefactureerd.
De geschiedenis gaat al gepseudonimiseerd mee; alleen teksten die de sessie zelf uitgaf, behouden hun plaatshouders. De sessie bewaart u zelf tussen aanvragen, versleuteld met een sleutel uit uw eigen sleutelbeheer.
Geef de namen van de betrokkenen, de werkgever of interne codes mee als eigen termen: tot 200 per aanvraag, hoofdletterongevoelig. Stuur alleen de termen van dít dossier mee; een lijst uit andere dossiers is zelf een persoonsgegeven.
De SDK werkt niet in een browser: de API-sleutel en de koppeling horen niet in een webpagina, en de dienst weigert elke aanvraag met een Origin-header. Draai de SDK in uw backend.
Beveiliging en gegevensverwerking
- Geen opslag van inhoud. De dienst schrijft geen inhoud weg: niet naar schijf, niet naar een databank, niet naar de log. Logregels bevatten alleen technische velden zoals status, route en omvang.
- De koppeling blijft bij u. De server ziet de koppeling tussen plaatshouder en waarde nooit en kan dus niets terugzetten.
- API-sleutels per organisatie. Een geheim van 256 bit, één keer getoond; wij bewaren alleen een SHA-256-hash. Per sleutel: scopes (tekst, documenten), profiel, IP-allowlist, vervaldatum en intrekking.
- EU. De gehoste vorm verwerkt in de EU, met de beheerdatabank in de EU. Self-hosted verwerkt waar u de container draait.
- Verwerkersovereenkomst. De gehoste vorm wordt alleen geleverd met een verwerkersovereenkomst; self-hosted valt onder een licentieovereenkomst en wij ontvangen geen inhoud.
- Geen tellingen per type. Gebruik wordt geteld in tekens, items, pagina's en aanvragen, nooit per soort persoonsgegeven. Zo ontstaat er geen afgeleide over gezondheid of vakbondslidmaatschap.
De LLM-aanbieder blijft een aparte ontvanger, waarvoor u zelf een grondslag, afspraken en een beoordeling van doorgiften buiten de EU nodig hebt. Pseudonimisering verkleint het risico van die doorgifte; ze maakt die afspraken niet overbodig. Kwetsbaarheden meldt u vertrouwelijk aan kevin@safeaiway.com; we antwoorden binnen 48 uur.
Limieten
| Grens | Waarde |
|---|---|
| Teksten per aanvraag | tot 100 |
| Document | tot 20 MiB |
| tot 300 pagina's |
De SDK verdeelt grote invoer zelf over opeenvolgende aanvragen. De volledige grenzen staan in de documentatie die u bij de pilot ontvangt.
Prijzen
U betaalt per teken dat geanalyseerd wordt, gemeten na normalisatie zoals elk antwoord het teruggeeft (usage.characters). Niet per LLM-token en niet per aanvraag, dus los van het taalmodel dat u kiest. Alle bedragen zijn exclusief btw.
| Plan | Prijs | Inbegrepen | Meerverbruik |
|---|---|---|---|
| Instap gehost, EU | € 49 per maand | 3 miljoen tekens | € 12 per miljoen tekens |
| Start gehost, EU | € 149 per maand | 10 miljoen tekens | € 8 per miljoen tekens |
| Business gehost, EU | € 399 per maand | 50 miljoen tekens | € 4 per miljoen tekens |
| Scale gehost, EU | € 999 per maand | 200 miljoen tekens | € 3 per miljoen tekens |
| Self-hosted container bij u | € 15.000 per jaar, plus € 3.000 eenmalige opstart | onbeperkt volume, één integratie, updates van de detectieregels | extra integratie € 3.000 per jaar |
| Documenten | € 300 per maand voor 10.000 pagina's, of € 0,05 per pagina | pdf per pagina; bij Word, Excel en CSV telt elke begonnen 3.000 tekens als een pagina | € 0,05 per pagina |
Ter oriëntatie: veertig consulenten die elk twintig vragen per dag stellen, gebruiken ongeveer 34 miljoen tekens per maand: op Start met meerverbruik ongeveer € 341, of € 8,50 per consulent. Vanaf ongeveer 11 miljoen tekens is Start voordeliger dan Instap, vanaf ongeveer 41 miljoen Business, vanaf 200 miljoen Scale.
We starten met pilots, op aanvraag en in de tijd begrensd, onder dezelfde overeenkomst als een productiegebruik: een licentie voor self-hosted, een verwerkersovereenkomst voor de gehoste vorm. De gehoste plannen worden geactiveerd na de pilotfase. Een offerte of contract gaat altijd voor op deze pagina.
Veelgestelde vragen
Is het resultaat anoniem?
Nee. Gepseudonimiseerde gegevens blijven voor u persoonsgegevens, want u hebt de koppeling. Of ze dat ook zijn voor de LLM-aanbieder, hangt af van wat er overblijft: een functie, een loon, een datum of een kleine organisatie kan iemand nog aanwijsbaar maken. Noem het resultaat daarom nooit anoniem.
Welke LLM kan ik gebruiken?
Elke taalmodeldienst die tekst ontvangt en tekst teruggeeft. De SDK krijgt uw eigen LLM-aanroep mee; de documentatie toont voorbeelden met de SDK's van OpenAI en Anthropic. Met de LLM-aanbieder heeft Safe AI Way geen contract.
Kan de SDK in de browser of in mijn webapp draaien?
Nee. De API-sleutel en de koppeling horen in uw backend. Uw webapp roept uw eigen backend aan, en die gebruikt de SDK (zie Zo bouwt u het in). De dienst weigert elke aanvraag die een Origin-header draagt.
Wat met gescande documenten?
Versie 1 heeft geen OCR. Een pdf met tekstlaag wordt per pagina verwerkt en pagina's zonder tekst worden gemeld; een volledig gescande pdf wordt geweigerd.
Is dit dezelfde technologie als de browserextensie?
Ja, het is dezelfde detectie-engine met dezelfde Belgische identificatoren en namenlijst. De API is bedoeld voor uw eigen software; de extensie beschermt medewerkers in AI-webtools.
