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.

Inhaltsverzeichnis

1 1. Unterstützte Methoden
2 2. Allgemein
3 3. Verwendung der Methoden
- 3.1 3.1 GET login/checkToken/{otok}
- 3.2 3.2 POST login
- 3.3 3.3 POST login/refresh
- 3.4 3.4 POST login/passwordLink
- 3.5 3.5 POST login/setPassword

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Authentifizierung	login/

2. 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.

3. Verwendung der Methoden

3.1 GET login/checkToken/{otok}

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:

{
    "id": <accountId aus dem Token>
}

Fehlercodes:

Fehler	Typ	Grund

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.

3.2 POST login

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.

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:

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

Fehlercodes:

Fehler	Typ	Grund

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.

3.3 POST login/refresh

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:

{
    "accessToken": <accessToken>
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden. \| Der Tokentyp ist nicht "Refresh".
400 Bad Request	"missing"	`refreshToken` fehlt.
401 Unauthorized		Der Token ist abgelaufen.
403 Forbidden		Das Konto ist gesperrt.
404 Not Found		Der Token oder das korrespondierende Konto wurden nicht gefunden.

3.4 POST login/passwordLink

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:

{
    "mailSuccessfullySent": true
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"missing"	`email` fehlt.
403 Forbidden		Das Konto ist gesperrt.
404 Not Found		Das Konto wurde nicht gefunden.
503 Service Unavailable	"internalError"	E-Mail konnte nicht gesendet werden.

3.5 POST login/setPassword

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:

{}

Fehlercodes:

Fehler	Typ	Grund

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.
403 Forbidden		Das Konto ist gesperrt.
404 Not Found		Das Konto wurde nicht gefunden.