API authorization tokens

Geautomatiseerde koppelingen die de REST API en/of SOAP API aanroepen, moeten bij elke call een "Authorization" HTTP request header meesturen. In deze header moet een geldig API authorization token staan, dat toegang geeft tot een account. Een HTTP request header ziet er daarom min of meer zo uit:

GET /path/to/endpoint HTTP/1.1
Host: api.copernica.com
Authorization: Bearer abcd.xyz.klmnop

Met curl is dit de call:

curl https://api.copernica.com/path/to/endpoint
   -H "Authorization: Bearer abcd.xyz.klmnop"

De authorization-header moet beginnen met het woord "Bearer" gevolgd door een base64 encoded token string.

Opmerking: De tokens zijn in werkelijkheid langer. En dit authorisatiesysteem is alleen van toepassing op de SOAP API en de REST API vanaf versie 4. Eerdere versies van de REST API gebruiken een ander authorisatiesysteem.

API authorization tokens en API access tokens

Copernica maakt onderscheid tussen API access tokens en API authorization tokens. De access tokens kun je aanmaken via het dashboard van de Marketing Suite of via een OAuth call. Dit token van je vervolgens via een call naar de authorization server omzetten naar een tijdelijk API authorization token waarmee je daarna de SOAP of REST API kunt aanroepen.

De authorization tokens hebben een beperkte houdbaarheid en zijn de aanbevolen manier om calls te doen naar de SOAP en REST API. Deze tokens kun je alleen programmatisch verkrijgen door middel van een call naar de authorization server. Eenmaal bemachtigd, kun je het token gedurende 24 uur voor meerdere calls gebruiken. Deze tokens zijn veilig, verlopen snel, en bevatten routeringsinformatie waarmee Copernica het verkeer efficiënt naar de juiste API backends kan sturen.

Hoewel we adviseren om alleen de door de authorisatie-server verstrekte tokens te gebruiken, functioneert de REST API ook met access tokens die nog niet zijn omgewisseld voor een authorization token. Dit gebruik is echter minder veilig en profiteert niet van de routeringsvoordelen van authorization tokens. Voor de SOAP API is een access token niet direct te gebruiken.

Naast handmatig aanmaken in Marketing Suite, kun je access tokens kun ook verkrijgen door middel van een OAuth handshake, wat handig is voor integraties die toegang moet krijgen tot accounts van derden.

Stappen om toegang te krijgen tot de APIs

1. Verkrijg een API access token: handmatig via het Marketing Suite dashboard of door middel van een OAuth handshake.
2. Verkrijg een API authorization token: Door een programmatische call naar de authorization server.
3. Gebruik het API authorization token: Voor calls naar de REST en/of SOAP API.
4. Herhaal stap 2 binnen 24 uur: Het verkregen token is maar 24 uur geldig is.

API access tokens aanmaken

API access tokens kun je handmatig aanmaken in Marketing Suite. Ga hiervoor naar Configuratie > Account > API access-tokens. Hier kun je een access token aanmaken en instellen of het token geschikt moet zijn voor de REST en/of de SOAP API.

Bij het aanmaken van een token moet je opgeven aan welke applicatie je het token wilt koppelen. Dit is met name van toepassing voor OAuth koppelingen. Het stelt je bijvoorbeeld in staat om in één keer een hele serie koppelingen uit te schakelen. Indien je geen gebruik maakt van OAuth kun je vaak het beste kiezen voor de standaard applicatie.

Opmerking: bij het aanmaken van een token kun je een aantal instellingen opgeven om de toegangsrechten op te geven. Maar nadat het token is aangemaakt, kun je het nogmaals aanklikken om nog meer instellingen op te geven.

Als je een token programmatisch wilt aanmaken, of als je access tokens wilt verkrijgen die toegang bieden tot accounts van derden, kun je gebruik maken van een OAuth handshake.

De authorization server

Een API authorization token kun je verkrijgen met een HTTP POST call naar https://authenticate.copernica.com. Het access token kan op twee manieren worden meegegeven. De voorkeur is om het token mee te sturen in de Authorization header:

POST / HTTP/1.1
Host: authenticate.copernica.com
Authorization: Bearer YOUR_API_ACCESS_TOKEN

Met curl ziet de call er als volgt uit:

curl -X POST https://authenticate.copernica.com
   -H "Authorization: Bearer YOUR_API_ACCESS_TOKEN"

Daarnaast wordt het meesturen van het token via een POST variabele "access_token" ondersteund:

curl -X POST https://authenticate.copernica.com
   -H "Content-Type: application/x-www-form-urlencoded"
   -d "access_token=YOUR_API_ACCESS_TOKEN"

Als beide methodes tegelijk worden gebruikt, dan wordt het token uit de Authorization header gebruikt.

Wat achtergrondinformatie

De authorization tokens zijn JSON Web Tokens. Mocht je dat willen, dan kun je het token dus decoderen en de JSON data uitlezen. Maar dit is niet nodig. Als je de tokens gewoon gebruikt als strings werkt het ook.