Authenticatie
API-sleutels, live- en proefsleutels, bevoegdheden, geldigheid, intrekken en het meegeven van de sleutel in een oproep.
De INTEGALL-API werkt enkel met API-sleutels. Er zijn geen gebruikerssessies en geen cookies.
Een sleutel krijgen#
De eigenaar of een beheerder van het transportbedrijf maakt een sleutel in het bedrijfspaneel, onder InstellingenIntegraties › API en webhooks. Aanmaken vraagt een verse code uit hun authenticator-app. Zie API-sleutels en webhooks.
De sleutel wordt maar één keer getoond. INTEGALL bewaart daarna enkel een hash; niemand kan de sleutel later nog lezen.
Soorten sleutels#
| Voorvoegsel | Soort | Gedrag |
|---|---|---|
rr_live_ | Live | Leest en schrijft echte gegevens. |
rr_test_ | Proef | Leest uw echte gegevens, maar een schrijfoproep wordt enkel gecontroleerd en niet opgeslagen. Antwoorden bevatten "sandbox": true en de header x-integall-sandbox: true. |
Een sleutel heeft de vorm rr_live_xxxxxxxx_ gevolgd door 32 tekens. De eerste 16 tekens (het voorvoegsel) ziet u ook in het paneel; daarmee herkent u een sleutel.
Bevoegdheden (scopes)#
| Bevoegdheid | In het paneel | Geeft toegang tot |
|---|---|---|
shipments:read | Zendingen lezen | GET /v1/shipments, GET /v1/shipments/{ref} |
shipments:write | Transporten aanvragen | POST /v1/shipment-requests |
invoices:read | Facturen lezen | GET /v1/invoices |
webhooks:manage | Webhooks beheren | geen pad in v1 |
Een oproep zonder de juiste bevoegdheid krijgt 403 met de code E_SCOPE.
De sleutel meegeven#
Gebruik bij voorkeur de header Authorization:
curl -H "Authorization: Bearer $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"De header X-API-Key werkt ook:
curl -H "X-API-Key: $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"Geldigheid en intrekken#
- Een sleutel is geldig tot hij ingetrokken wordt, of 30, 90 of 365 dagen (keuze bij het aanmaken).
- Intrekken werkt meteen, ook tussen twee oproepen: INTEGALL controleert de sleutel bij elke oproep opnieuw.
- Een onbekende, ingetrokken of verlopen sleutel krijgt altijd hetzelfde antwoord:
401metE_AUTH. INTEGALL zegt nooit waarom een sleutel ongeldig is. - Een bedrijf heeft hoogstens 20 actieve sleutels.
Een sleutel vervangen#
- Laat een nieuwe sleutel maken.
- Zet de nieuwe sleutel in uw systeem.
- Laat de oude sleutel intrekken.