Authenticatie

Je authenticeert bij de Puntjes API met OAuth2, via de client credentials-grant. Dat is een machine-to-machine flow voor kassasystemen, backend-services en integraties die in naam van een handelaar werken.

---

Client credentials aanmaken

Je maakt en beheert API-clients in het beheerdersportaal. Ga in de zijbalk naar API-clients. Daar kun je:

• Een nieuwe API-client aanmaken met een label
• Je client ID bekijken
• Je client secret tonen of opnieuw genereren
• Clients intrekken waarvan het secret niet meer geheim is

Elke OAuth-client hoort bij één handelaar. Authenticeer je met de credentials van die client, dan blijft alles wat je daarna doet binnen die ene handelaar.

---

Een access token aanvragen

Ruil je client credentials om voor een access token met een POST-request naar het OAuth-token-endpoint:

curl -X POST https://puntjes.app/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id=JOUW_CLIENT_ID \
  -d client_secret=JOUW_CLIENT_SECRET

Response

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJS..."
}

Veld	Beschrijving
token_type	Altijd Bearer
expires_in	Hoe lang het token meegaat, in seconden (standaard: 3600 = 60 minuten)
access_token	Het JWT dat je in elk API-request meestuurt

---

Het token gebruiken

Zet het access token in de Authorization-header van elk API-request:

curl https://puntjes.app/api/v1/customers/lookup?identifier=CARD-001 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS..."

---

Wanneer een token vervalt

Een access token gaat 60 minuten mee. Daarna antwoordt de API met 401 Unauthorized. Je integratie moet dan drie dingen doen:

1. Vang de 401 op
2. Vraag een nieuw access token aan
3. Stuur het oorspronkelijke request opnieuw

---

Scope per handelaar

Je token bepaalt van welke handelaar je de gegevens ziet. De OAuth-client hangt aan één handelaar, dus:

• Elke klant, transactie, beloning en campagne die je terugkrijgt, hoort bij jouw zaak
• Aan gegevens van een andere handelaar kom je niet
• Wat je aanmaakt (klanten, transacties) komt vanzelf bij jouw zaak te staan

---

Welke status je zaak moet hebben

Je zaak moet op actief staan om de API te gebruiken. Staat ze op:

• Opgeschort: de API blijft werken zolang de respijtperiode loopt. Die periode wordt per handelaar ingesteld. Daarna volgt 403 VENDOR_SUSPENDED
• Gedeactiveerd: de API gaat meteen dicht, met 403 VENDOR_DEACTIVATED
• In behandeling: de API blijft dicht tot de zaak geactiveerd is

Daarnaast staat er nog een controle. Zodra een betaalde periode is verstreken en je abonnement is afgelopen, blijven leesacties 200 antwoorden en geeft elke schrijfactie 403 SUBSCRIPTION_EXPIRED. Opnieuw proberen helpt niet: de weg terug is dat iemand een plan kiest. Een beheerder van je zaak doet dat zelf onder Facturatie, en daarom is dit een 403 en geen 429 die vanzelf wegtrekt.

---

Veilig omgaan met je credentials

• Bewaar client secrets op een veilige plek: zet ze nooit in frontend-code of in je versiebeheer
• Spreek de API alleen over HTTPS aan
• Ververs je client secrets periodiek met Secret opnieuw genereren in het beheerdersportaal
• Trek een client meteen in zodra je twijfelt of het secret nog geheim is
• Geef elke kassa en elke integratie een eigen API-client, zodat je achteraf ziet welk systeem wat deed