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

GET login/checkToken/

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.

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.

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.

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

{
    "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.

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": "[e-mail]"
}

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.

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

{
    "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.

POST login/logout

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.