API-Referenz Authentifizierung

Die API-Referenz Authentifizierung beschreibt, wie sich Benutzer über die REST-API anmelden können. Die Anmeldung erfolgt mit einem Benutzerkonto, das im Admin-Interface des Shops verwaltet wird. Nach erfolgreicher Authentifizierung können je nach zugewiesenen Rechten weitere REST-API-Endpunkte genutzt werden, beispielsweise um Anfragen zu bearbeiten oder Bestellungen zu verwalten.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Authentifizierung	login/

Allgemein

Um auf die REST API zugreifen zu können, benötigen Sie ein Benutzerkonto für das Admin-Interface des Shops. Die Rechte und Rollen dieses Kontos steuern, auf welche REST-API-Endpunkte Sie zugreifen dürfen und welche HTTP-Methoden (GET, POST, PUT, DELETE) Ihnen zur Verfügung stehen. Beispiel:

Ein Benutzer mit nur Leserechten kann Anfragen abrufen, aber nicht bearbeiten oder löschen.
Ein Benutzer mit Administratorrechten hat vollen Zugriff auf alle REST-Dienste und Methoden.

Wenn der Zugriff auf bestimmte REST-Endpunkte verweigert wird, fehlt Ihrem Benutzerkonto vermutlich die entsprechende Berechtigung. Wenden Sie sich in diesem Fall an den zuständigen Shop-Administrator. Weitere Informationen zur Verwaltung von Benutzern und zur Vergabe von Rechten finden Sie im Abschnitt API-Referenz Benutzerverwaltung.

Access Token mitsenden

Nach der Anmeldung über POST login senden Sie das accessToken bei jedem weiteren Aufruf im Header X-Authorization mit. Der Wert besteht aus dem Wort Bearer, gefolgt vom Token:

X-Authorization: Bearer <accessToken>

Der Shop sucht das Token in dieser Reihenfolge:

Header X-Authorization
Header Authorization, wenn X-Authorization fehlt
URL-Parameter token, wenn beide Header fehlen

Sendet ein Aufruf beide Header, gilt X-Authorization. Ist dem Shop ein eigener Zugriffsschutz vorgeschaltet, beispielsweise eine Anmeldung per Basic Auth, stehen dessen Angaben im Header Authorization. In diesem Fall werden sie dann nicht als Access Token gelesen, solange das Token in X-Authorization steht. Fehlt das Token oder ist es ungültig oder abgelaufen, antwortet die API mit dem Status 401.

Verwendung der Methoden

Dieser Endpunkt überprüft ein Double-Opt-in-Token (otok) auf Gültigkeit. Er wird beispielsweise im Rahmen des Passwort-Zurücksetzen-Prozesses verwendet.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/login/checkToken/<Token>

Antwort

{
    "success": true,
    "id": <accountId aus dem Token>
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request	”missing”	`otok` fehlt.
400 Bad Request	”invalidValue”	`otok` ist ungültig oder schon genutzt oder ermöglicht es nicht, das Passwort zu ändern.
404 Not Found		Das Konto wurde nicht gefunden.

Dieser Endpunkt ermöglicht die Anmeldung über E-Mail/Passwort oder einen API-Schlüssel (apiKey). Bei erfolgreicher Authentifizierung werden ein accessToken und ein refreshToken zurückgegeben. Wird der Parameter ?setCookie in der URL angegeben, werden die Tokens als Cookies gesetzt und das refreshToken wird nicht in der JSON-Antwort zurückgegeben.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/login

Request Body

{
    "grantType": "apiKey",
    "apiKey": <api key>
}

oder

{
    "grantType": "password",
    "user": <username>,
    "password": <password>
}

Antwort

{
    "success": true,
    "accessToken": <accessToken>,
    "refreshToken": <refreshToken>
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden.
401 Unauthorized		Das Konto hat `id` 0.
403 Forbidden		Das Konto ist gesperrt.
404 Not Found		Das Konto konnte nicht geladen werden.
503 Service Unavailable	”internalError”	Refresh-Token konnte nicht erstellt werden.

Dieser Endpunkt stellt ein neues accessToken aus, das über ein gültiges refreshToken autorisiert wird. Wird der Parameter ?setCookie in der URL angegeben, setzt der Endpunkt das neue accessToken zusätzlich als Cookie.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/login/refresh

Request Body

{
    "refreshToken": <refreshToken>
}

Antwort

{
    "success": true,
    "accessToken": <accessToken>
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden. Der Tokentyp ist nicht “Refresh”.
400 Bad Request	”invalidFormat”	`refreshToken` hat einen ungültigen Typ (erwartet: String).
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
401 Unauthorized		Der Token ist abgelaufen.
403 Forbidden		Das Konto ist gesperrt.
404 Not Found		Der Token oder das korrespondierende Konto wurden nicht gefunden.

Dieser Endpunkt versendet eine E-Mail mit einem Link zum Zurücksetzen des Passworts an die angegebene E-Mail-Adresse. Solange ein zuvor angeforderter Link noch aktiv ist, wird kein neuer Link versendet. Ein neuer Link kann erst 30 Minuten nach der letzten Anforderung angefordert werden.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/login/passwordLink

Request Body

{
    "email": "m.mustermann@websale.de"
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`email` fehlt.
400 Bad Request	”invalidValue”	`email` ist ein leerer String.
400 Bad Request	”invalidFormat”	`email` ist kein String.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
404 Not Found		Das Konto wurde nicht gefunden.
409 Conflict	”active”	Für das Konto wurde in den letzten 30 Minuten bereits ein Link angefordert.
503 Service Unavailable	”internalError”	E-Mail konnte nicht gesendet werden.

Über diesen Endpunkt wird ein neues Passwort für ein Benutzerkonto gesetzt. Die Aktion muss durch ein gültiges Double-Opt-in-Token autorisiert werden, das zuvor per E-Mail (login/passwordLink) versendet wurde.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/login/setPassword

Request Body

{
    "password_new": <new password>,
    "password_new_again": <new password>,
    "otok": <double opt-in token>
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden. Das `Double-Opt-in-Token` ist ungültig oder ermöglicht es nicht, das Passwort zu ändern. Das Passwort ist zu schwach.
400 Bad Request	”missing”	`Double-Opt-in-Token`, `password_new` oder `password_new_again` fehlen.
400 Bad Request	”invalidValue”	`password_new` und `password_new_again` stimmen nicht überein. Das Passwort ist kürzer als 12 Zeichen. `password_new`, `password_new_again` oder `otok` sind leere Strings.
400 Bad Request	”invalidFormat”	`password_new`, `password_new_again` oder `otok` sind keine Strings.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
403 Forbidden		Das Konto ist gesperrt.
404 Not Found		Das Konto wurde nicht gefunden.

Dieser Endpunkt meldet den aktuellen Benutzer ab. Dabei werden die gesetzten Cookies für accessToken und refreshToken gelöscht und der Refresh-Token aus der Datenbank entfernt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/login/logout

Request Body

{}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

Allgemein

Access Token mitsenden

Verwendung der Methoden

Beispiel

Antwort

Fehlercodes

Beispiel

Request Body

Antwort

Fehlercodes

Beispiel

Request Body

Antwort

Fehlercodes

Beispiel

Request Body

Antwort

Fehlercodes

Beispiel

Request Body

Antwort

Fehlercodes

Beispiel

Request Body

Antwort

Fehlercodes

​Unterstützte Methoden

​Allgemein

​Access Token mitsenden

​Verwendung der Methoden

​GET login/checkToken/{otok}

​Beispiel

​Antwort

​Fehlercodes

​POST login

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST login/refresh

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST login/passwordLink

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST login/setPassword

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST login/logout

​Beispiel

​Request Body

​Antwort

​Fehlercodes

Unterstützte Methoden

Allgemein

Access Token mitsenden

Verwendung der Methoden

GET login/checkToken/{otok}

Beispiel

Antwort

Fehlercodes

POST login

Beispiel

Request Body

Antwort

Fehlercodes

POST login/refresh

Beispiel

Request Body

Antwort

Fehlercodes

POST login/passwordLink

Beispiel

Request Body

Antwort

Fehlercodes

POST login/setPassword

Beispiel

Request Body

Antwort

Fehlercodes

POST login/logout

Beispiel

Request Body

Antwort

Fehlercodes