Authenticatie

Elke aanroep naar de API is authenticatie met een Percelio Inzicht-sleutel, als HTTP bearer-token.

De Authorization-header

Stuur de sleutel in de Authorization-header, voorafgegaan door Bearer:

Authorization: Bearer pct_…

Geen querystring, geen cookie, geen OAuth-flow. De bearer-sleutel is het enige credential dat de API accepteert. Altijd over HTTPS, behandel hem als een wachtwoord.

curl https://percelio.nl/api/v1/whoami \
  -H "Authorization: Bearer pct_…"

Een ontbrekende of ongeldige sleutel krijgt 401:

{"fout": "Ongeldige of ontbrekende sleutel."}

Een sleutel maken

In Percelio, open Instellingen en maak een Inzicht-sleutel. De sleutel bestaat één keer: wij bewaren alleen de hash. Wie hem kwijt is, roteert hem — de oude stopt meteen, de nieuwe is één keer te kopiëren.

Een account mag maximaal 10 geldige inzicht-sleutels tegelijk hebben. Roterende sleutels trekken de oude in, dus die tellen niet mee.

Rechten

Een inzicht-sleutel draagt inzicht:lezen. Zonder dat recht is elke Inzicht-aanroep 403. Een beheer-sleutel mag Inzicht niet, een inzicht-sleutel mag Beheer niet. Whoami vertelt welke familie je in handen hebt.

Whoami

Het eerste dat je aanroept. Het antwoord zegt wat de sleutel mag, tot wanneer hij geldig is, en hoeveel credits er nog op het account staan.

GET https://percelio.nl/api/v1/whoami
Authorization: Bearer pct_…

{
  "data": {
    "naam": "productie",
    "familie": "inzicht",
    "voorvoegsel": "pct_ab12",
    "rechten": ["inzicht:lezen"],
    "bereik": "account",
    "verloopt_op": "2027-09-16T12:00:00+02:00",
    "saldo": {
      "credits": 1000,
      "eenheid_cent": 5,
      "tegoed_cent": 5000
    }
  },
  "meta": {
    "schema": "percelio/api",
    "schema_versie": "1.0"
  }
}

Whoami kost geen credits, zodat je ook kunt kijken als het tegoed op is.