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, z. B. zum Bearbeiten von Anfragen oder Verwalten von Bestellungen.

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.

Verwendung der Methoden

Dieser Endpunkt überprüft ein Double-Opt-in-Token (otok) auf Gültigkeit. Er wird z. B. 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.

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.
503 Service Unavailable	”internalError”	E-Mail konnte nicht gesendet werden.

Dieser Endpunkt setzt ein neues Passwort für ein Benutzerkonto. Die Aktion muss durch ein gültiges Double-Opt-in-Token autorisiert sein, das zuvor per E-Mail (login/paswordLink) 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

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

​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

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