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. Authorization tokens hebben een beperkte houdbaarheid en zijn nodig voor calls 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.

In tegenstelling tot een authorization token, kun je een API access token wel handmatig aanmaken. Dit kan via het Marketing Suite dashboard. Dit token geeft nog niet direct toegang tot de APIs, maar je kunt er wel een authorization token mee opvragen door middel van een call naar de authorization server.

Access tokens kun je 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. De body van het request moet de POST variabele "access_token" bevatten waarin het access token staat. De server stuurt een authorization token terug. Jouw request moet er dus min of meer als volgt uitzien:

POST / HTTP/1.1
Host: authenticate.copernica.com
Content-Length: 34
Content-Type: application/x-www-form-urlencoded

access_token=YOUR_API_ACCESS_TOKEN

Je kunt de call bijvoorbeeld vanaf de command line als volgt simuleren:

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

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.