Nieuwe REST API v4 met JWT-autorisatie

Vandaag introduceert Copernica versie 4 van de REST API. Deze nieuwe versie heeft een ander login- en autorisatiesysteem om de veiligheid te vergroten. De login-tokens maken voortaan niet langer deel uit van de URL en zijn daardoor minder kwetsbaar als een API-URL wordt geknipt en geplakt. Bovendien hebben de tokens een kortere levensduur om de kans verder te verkleinen dat ze in verkeerde handen vallen.

Wat is er nieuw?

In de REST API v4 wordt gebruik gemaakt van autorisatie via de "Authorization" HTTP header. In eerdere versies van onze REST API was het verplicht om een access-token mee te geven in de URL van het verzoek. In de nieuwe versie is dit niet meer nodig. Voor alle v4 API-calls is het vereist dat je een "Authorization" HTTP header meestuurt met daarin een JSON web token (kortweg: JWT).

Wat moet je doen om over te stappen?

De oude API-endpoints (v1, v2 en v3) blijven voorlopig werken. Bestaande koppelingen hoeven dus nog niet te worden aangepast. We raden echter aan om over te stappen op de v4 API, omdat je koppeling hierdoor veiliger wordt. Bovendien heeft de v4 API wat onzichtbare wijzigingen waardoor de performance beter is, en er beter met piekbelastingen kan worden omgegaan.

In de online documentatie leggen we precies uit hoe je een koppeling met de v4 API maakt. In het kort moet je de volgende zaken veranderen:

• Stap 1: voordat je een call naar de REST API kunt doen, moet je eerst een autorisatie-token aanvragen door een HTTP POST-call naar https://authenticate.copernica.com te sturen.
• Stap 2: het token dat je in stap 1 terugkrijgt blijft 24 uur geldig en kun je daarna voor meerdere calls gebruiken.
• Stap 3: pas daarna kun je de REST API aanroepen zoals je voorheen ook deed, maar nu zonder API-token in de URL, maar met een extra authorization: header en het token dat je terugkreeg in stap 1.

Om de v4 API te gebruiken moet je dus een extra call toevoegen aan je bestaande koppelingen om het autorisatie-token te verkrijgen. En je moet een extra HTTP-header toevoegen aan alle calls. Voor heel eenvoudige API-scripts is dit wat overhead: waar je vroeger maar één call deed, zijn nu twee calls nodig. Voor de meeste koppelingen valt deze overhead echter wel mee, omdat het token 24 lang geldig blijft.

Wat kun je met de API doen?

De API biedt directe toegang tot Copernica-functionaliteiten zonder gebruik te hoeven maken van de interface. Je voert acties uit door HTTP-verzoeken te versturen. Het type verzoek (GET, POST, PUT of DELETE) is afhankelijk van de actie die je uitvoert. Denk bijvoorbeeld aan het updaten van een profiel, het aanmaken van een collectie of het verwijderen van een veld.

Zodra je verzoek verwerkt is retourneert de API een respons (statuscode). Aan de hand daarvan weet je of de actie succesvol is uitgevoerd.

Meer informatie over JWT

De tokens die we gebruiken zijn JSON Web Tokens. Wil je meer weten over JWT? Neem een kijkje op JWT.io.