API voor ontwikkelaars

Inloggen met OAuth

Je app krijgt toegang via OAuth 2.1, met PKCE: de klant logt in bij Amfy en geeft je app toestemming. Je app krijgt dan een access-token, geen wachtwoord of sleutel. De meeste OAuth-bibliotheken doen de stappen hieronder zelf, met de gegevens uit https://api.amfy.nl/.well-known/oauth-authorization-server.

1. Je app registreren

Eén keer: je krijgt een client_id, een lange tekst die je bewaart zoals hij is. Als redirect_uri gebruik je een adres op je eigen computer (http://127.0.0.1 of http://localhost, de poort mag later anders zijn) of een https-adres van je eigen website. Een client secret is er niet: je app bewijst zich met PKCE.

curl https://api.amfy.nl/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Mijn dashboard", "redirect_uris": ["http://127.0.0.1:8765/callback"]}'

{
  "client_id": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiTWlqbiBkYXNoYm9hcmQiLCJydXJpcyI6…",
  "client_id_issued_at": 1792324206,
  "client_name": "Mijn dashboard",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "read"
}

Heeft je app een https-adres met een Client ID Metadata Document, dan mag die URL ook direct de client_id zijn; registreren is dan niet nodig.

2. Inloggen in de browser

Maak een willekeurige code_verifier (43 tot 128 tekens) en de code_challenge daarbij: de SHA-256 ervan, in base64url zonder =. Open dan deze URL in de browser:

https://api.amfy.nl/oauth/authorize
  ?response_type=code
  &client_id=JOUW_CLIENT_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback
  &code_challenge=JOUW_CODE_CHALLENGE
  &code_challenge_method=S256
  &state=WILLEKEURIGE_TEKST

De klant logt in en kiest Toegang geven. De browser gaat dan naar je redirect_uri, met een code die tien minuten geldig is:

http://127.0.0.1:8765/callback?code=CODE&iss=https%3A%2F%2Fapi.amfy.nl&state=WILLEKEURIGE_TEKST

Controleer dat state klopt. Kiest de klant Annuleren, dan krijg je error=access_denied in plaats van een code. Klopt je verzoek zelf niet (bijvoorbeeld zonder PKCE), dan toont de pagina de fout en gaat de browser niet terug naar je app.

3. Tokens ophalen

curl https://api.amfy.nl/oauth/token \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d redirect_uri=http://127.0.0.1:8765/callback \
  -d client_id=JOUW_CLIENT_ID \
  -d code_verifier=JOUW_CODE_VERIFIER

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "amfy_rt_…",
  "scope": "read"
}

Het access-token is een uur geldig. Daarna haal je een nieuw op met het refresh-token. Je krijgt dan ook een nieuw refresh-token: bewaar dat, want het oude werkt na een minuut niet meer. Gebruik je een oud refresh-token later toch nog eens, dan vervalt de koppeling en moet de klant opnieuw inloggen. Ververs niet vanuit twee processen tegelijk: dan blijft maar een van de twee nieuwe refresh-tokens werken.

curl https://api.amfy.nl/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=amfy_rt_… \
  -d client_id=JOUW_CLIENT_ID

Per klant heeft je app één koppeling: logt de klant op een tweede apparaat in, dan werkt het refresh-token van het eerste niet meer. Een refresh-token dat 90 dagen niet is gebruikt, verloopt. Uitloggen in je app doe je met POST /oauth/revoke: stuur het refresh-token en je client_id mee (RFC 7009).

Je access-token gebruiken

Stuur het access-token bij elk verzoek mee in de header Authorization, met het woord Bearer en een spatie ervoor:

curl https://api.amfy.nl/api/v1/chargers \
  -H "Authorization: Bearer JOUW_ACCESS_TOKEN"

Antwoorden zijn JSON. Tijden zijn in UTC (bijvoorbeeld 2026-10-17T16:30:00Z), datums schrijf je als 2026-10-17, energie is in kWh en bedragen zijn in eurocenten.

Laadpalen ophalen

GET /api/v1/chargers geeft al je laadpalen, de oudste eerst. Eén laadpaal haal je op met GET /api/v1/chargers/{id}.

{
  "chargers": [
    {
      "id": "3f6c2a1e-8b4d-4e2a-9c1f-5d7e8a9b0c12",
      "name": "Laadpaal thuis",
      "brand": "Zaptec",
      "model": "Go 2",
      "status": "active",
      "startsOn": "2026-01-01",
      "connectedAt": "2026-10-15T07:12:00Z",
      "createdAt": "2026-10-14T18:00:00Z"
    }
  ]
}

Status

Laadsessies ophalen

GET /api/v1/sessions geeft je laadsessies, de nieuwste eerst. Met deze parameters kies je welke:

curl "https://api.amfy.nl/api/v1/sessions?from=2026-09-01&to=2026-10-01&limit=1" \
  -H "Authorization: Bearer JOUW_ACCESS_TOKEN"

{
  "sessions": [
    {
      "id": "9a1d5e0b-2c7f-4f43-8e6a-1b2c3d4e5f60",
      "chargerId": "3f6c2a1e-8b4d-4e2a-9c1f-5d7e8a9b0c12",
      "chargerName": "Laadpaal thuis",
      "startedAt": "2026-09-29T16:30:00Z",
      "endedAt": "2026-09-29T19:30:00Z",
      "kwh": 16.375,
      "amount": 206,
      "final": false,
      "meterStart": 1348.5,
      "meterEnd": 1364.875
    }
  ],
  "limit": 1,
  "offset": 0,
  "totals": {
    "count": 15,
    "kwh": 245.625,
    "amount": 3096,
    "final": false
  }
}

Zolang offset plus limit kleiner is dan totals.count, zijn er meer sessies: vraag dezelfde lijst opnieuw op met een hogere offset (20, 40, …). Voor een totaal hoef je niet door te bladeren: dat staat al in totals. Laadsessies van vóór de ingangsdatum van je laadpaal tellen niet mee en staan er niet in.

Nieuwe laadsessies komen een paar keer per dag binnen, zodra wij ze bij de fabrikant van je laadpaal hebben opgehaald. Vaker dan eens per kwartier vragen heeft dus geen zin.

Fouten en limieten

Gaat er iets mis, dan krijg je een HTTP-status en een antwoord met een uitleg (error), een vaste code (code) en bij een ongeldige parameter de naam ervan (field):

{
  "error": "to moet na from liggen.",
  "code": "invalid_request",
  "field": "to"
}

Fouten bij het inloggen (/oauth/token) volgen OAuth: error en error_description, bijvoorbeeld invalid_grant voor een verlopen code of refresh-token. Per account kun je ongeveer 60 verzoeken per minuut doen, de API en MCP samen.

Toegang intrekken

In de Amfy-app zie je onder Profiel → Gekoppelde apps welke apps toegang hebben, wanneer je ze koppelde en wanneer ze voor het laatst iets ophaalden. Kies Intrekken en de app kan meteen niet meer bij je gegevens; ook een token dat hij al had, werkt dan niet meer.

Wil je de app later weer gebruiken, koppel hem dan opnieuw vanuit de app zelf. Een app die 90 dagen niets bij ons ophaalt, moet je ook opnieuw koppelen.

Veiligheid en privacy

• Een gekoppelde app leest alleen je laadpalen en laadsessies. Je profiel, je rekeningnummer en je uitbetalingen zitten er niet in, en veranderen kan niet.
• Je logt altijd in bij Amfy zelf, op api.amfy.nl. De app die je koppelt, ziet je e-mailadres en je code niet.
• Voordat je toegang geeft, zie je welke app het is en waar je daarna naartoe gaat. Herken je de app niet, kies dan Annuleren.
• Wij bewaren de tokens van een app niet zelf, alleen een onleesbare afgeleide (hash). Trek je de toegang in, dan werken ze meteen nergens meer.
• Wat een andere app of assistent met je gegevens doet, valt onder het privacybeleid van die app. Hoe wij met je gegevens omgaan, lees je in de privacyverklaring.

Vragen over de API? Mail ons via [email protected].