> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Referenz Authentifizierung

> Anmeldung an der Admin Interface API per Benutzerkonto oder API-Schlüssel, Access- und Refresh-Token verwalten sowie Passwörter zurücksetzen.

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/        | <br /><Icon icon="check" /> | <br /><Icon icon="check" /> | <br /><Icon icon="ban" /> | <br /><Icon icon="ban" /> |

## 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](/schnittstellen/admin-interface-api/api-referenz-benutzerverwaltung).

## Verwendung der Methoden

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/login/checkToken/<Token>
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/login
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "grantType": "apiKey",
    "apiKey": <api key>
}
```

oder

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "grantType": "password",
    "user": <username>,
    "password": <password>
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/login/refresh
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "refreshToken": <refreshToken>
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true,
    "accessToken": <accessToken>
}
```

#### Fehlercodes

| **Fehler**       | **Typ**            | **Grund**                                                                          |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------- |
| 400 Bad Request  |                    | Request body konnte nicht geladen werden. <br /> 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/login/passwordLink
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "email": "m.mustermann@websale.de"
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/login/setPassword
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "password_new": <new password>,
    "password_new_again": <new password>,
    "otok": <double opt-in token>
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Fehlercodes

| **Fehler**      | **Typ**            | **Grund**                                                                                                                                                                             |
| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 Bad Request |                    | Request body konnte nicht geladen werden. <br /> Das `Double-Opt-in-Token` ist ungültig oder ermöglicht es nicht, das Passwort zu ändern. <br /> 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.<br />Das Passwort ist kürzer als 12 Zeichen.<br />`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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/login/logout
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Fehlercodes

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