> For the complete documentation index, see [llms.txt](https://helpcenter.etron.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpcenter.etron.info/verwaltungsoberflache/api-and-hooks/authentication.md).

# Authentication

API Authentifizierung, OAuth2, OAuth, Postman, Access Token, Client Key, Client Secret

{% hint style="success" %}
*Modul: ETRON onRetail REST API*
{% endhint %}

> *API & Hooks -> Authentication*

<div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2F4EWs5LaYmar48uVIXLWM%2Fimage.png?alt=media&amp;token=5727f1c6-8066-4180-bb7c-aeca4f5e9709" alt="API &#x26; Hooks -> Authentication"><figcaption><p>API &#x26; Hooks -> Authentication</p></figcaption></figure></div>

{% hint style="info" %}
*Über Authentication werden OAuth2-Zugangsdaten für externe Programme verwaltet. Der Zugriff auf die REST-API wird damit auf berechtigte Verbindungen beschränkt.*
{% endhint %}

Damit ein externes Programm auf die REST-API zugreifen kann, werden gültige Zugangsdaten benötigt. Über **Authentication** wird festgelegt, welche Programme verbunden werden dürfen und welche Rechte verwendet werden. Jede Verbindung wird über OAuth2 aufgebaut. Dies gilt für eigene Software, andere Systeme und Testwerkzeuge wie [Postman](https://www.postman.com/downloads/).

Es stehen zwei Vorgehensweisen zur Verfügung:

* **Schnelleinstieg mit Postman:** Ein vorkonfiguriertes Postman-Paket wird direkt heruntergeladen. Das Paket wird zum schnellen Testen der API in Postman verwendet.
* **Eigene Authentifizierung:** Für ein Drittprogramm wird ein eigener OAuth2-Zugang angelegt. Dabei werden ein eigener Name, ein eingeschränkter Benutzer und eigene Zugangsdaten verwendet. Dieser Zugang kann mit jedem OAuth2-fähigen Programm verwendet werden.

### Schnelleinstieg: Postman-Paket verwenden

{% hint style="warning" %}
*Das Paket enthält gültige Zugangsdaten der jeweiligen Instanz. Die Datei ist wie ein Passwort zu behandeln. Eine öffentliche Weitergabe oder Ablage in Tickets und Versionsverwaltungen ist zu vermeiden.*
{% endhint %}

Über [API & Hooks -> Endpunkte -> Documentation](/verwaltungsoberflache/api-and-hooks/endpunkte/documentation-v2-rest-api-dokumentation.md) steht **Download Postman Collection & Environment** zur Verfügung. Es wird ein ZIP-Archiv mit der vollständigen Collection und einer vorkonfigurierten Umgebung heruntergeladen.

Die Umgebung wird mit `base_url`, Client Key und Client Secret der jeweiligen Instanz befüllt. Der Import des Archivs und der Collection ist unter [Documentation: v2 REST API Dokumentation](/verwaltungsoberflache/api-and-hooks/endpunkte/documentation-v2-rest-api-dokumentation.md) beschrieben. Dort wird auch eine Collection-Datei ohne Zugangsdaten bereitgestellt.

Nach dem Import werden folgende Schritte durchgeführt:

1. Die Umgebung **onRetail V2** wird in Postman als aktive Umgebung ausgewählt.
2. In der Collection wird **Authorization** geöffnet.
3. Unter **Configure New Token** wird **Get New Access Token** ausgewählt.
4. Das Token wird abgerufen und mit **Use Token** übernommen.

Danach können API-Abfragen ohne eigene Authentifizierung durchgeführt werden.

### Eigene Authentifizierung anlegen

Die erzeugten Zugangsdaten sind nicht an Postman gebunden. Die Zugangsdaten können von jedem OAuth2-fähigen Programm verwendet werden. Die Hinterlegung in Postman wird nachfolgend beispielhaft beschrieben.

{% stepper %}
{% step %}

#### Authentifizierung in ETRON onRetail erstellen

> *API & Hooks -> Authentication*

1. Eine neue Authentifizierung wird angelegt.
2. Folgende Einstellungen werden gesetzt:
   * **Name:** Name des Drittprogramms
   * **OAuth Type:** Client Credentials
   * **User:** Für die API verwendeter Benutzer
3. Alle weiteren Felder bleiben unverändert.
4. Die Authentifizierung wird gespeichert.

<div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2Fmdj5G4EUqiW8dAoWhMdy%2Fimage.png?alt=media&amp;token=21e80154-7ba8-4f7f-b6f8-3cbfd8cd351f" alt="Name, OAuth Type und User werden gesetzt"><figcaption><p>Name, OAuth Type und User werden gesetzt</p></figcaption></figure></div>

Die Werte **Client Key** und **Client Secret** werden für die Authentifzierung über die API-Plattform benötigt.
{% endstep %}

{% step %}

#### Collection in Postman vorbereiten

{% hint style="info" %}
*Für die manuelle Einrichtung wird dieselbe Collection wie beim Schnelleinstieg verwendet. Sie steht über*[ *API & Hooks -> Endpunkte -> Documentation -> Download Postman Collection & Environment*](/verwaltungsoberflache/api-and-hooks/endpunkte/documentation-v2-rest-api-dokumentation.md#download-api-postman-collection-postman-environment) *zur Verfügung.*
{% endhint %}

1. Die heruntergeladene Collection in Postman über die Schaltfläche "Import" importieren. Dabei kann eine einzelne Datei oder ein Ordner ausgewählt werden.<br>

   <div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2Fxnqxk2a4YMMLWpUO9s1e%2Fimage.png?alt=media&amp;token=b61e134e-5938-4377-b9e6-fcd83250dcef" alt="Import einer Collection in Postman"><figcaption><p>Import einer Collection in Postman</p></figcaption></figure></div>
2. Nach dem Import die Collection in Postman öffnen.
3. Den Tab **Variables** auswählen.
4. Die Variable `base_url` anlegen
   * **Current Value:** URL der Instanz, beispielsweise `https://xxxxxx.wawi.onretail.eu`\
     Die URL wird ohne abschließenden `/` hinterlegt.
   * Optional können `client_id` und `client_secret` als Variablen hinterlegt werden. Als **Current Value** werden Client Key und Client Secret eingetragen.

<div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2F1zPmRrVXx35fnmcyz0As%2Fimage.png?alt=media&amp;token=bd9abc3f-549e-42fa-8bb2-e88e278de743" alt="Variablenübersicht in Postman"><figcaption><p>Variablenübersicht in Postman</p></figcaption></figure></div>

5. In den Tab **Authorization** wechseln, um die Authentifzierung zu konfigurieren.
6. Als **Type** wird **OAuth 2.0** gesetzt.

   <div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2F0khiicFEOUkKtkFvkbrx%2Fimage.png?alt=media&amp;token=c8819329-3f08-4019-adfb-2aa69a78d748" alt="OAuth 2.0 als Auth Type in Postman"><figcaption><p>OAuth 2.0 als Auth Type in Postman</p></figcaption></figure></div>

{% endstep %}

{% step %}

#### Access Token konfigurieren

1. Im Tab **Authorization** zum Bereich **Configure New Token** scrollen.
2. Folgende Werte eintragen:
   * **Token Name:** frei wählbar, beispielsweise *ETRON onRetail Postman Token*
   * **Grant Type:** Client Credentials
   * **Access Token URL:** `{{base_url}}/api/v2/authentication/oauth2/token`
   * **Client ID:** Client Key aus ETRON onRetail oder `{{client_id}}` (wenn als Variable angelegt)
   * **Client Secret:** Client Secret aus ETRON onRetail oder `{{client_secret}}` (wenn als Variable angelegt)
   * **Client Authentication:** Send as Basic Auth header

<div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2FxQ46oo9JU7sbyhFylaAF%2Fimage.png?alt=media&amp;token=c0bc53b1-8077-400a-8cb5-27d06e990f02" alt="Neue Tokenkonfiguration in Postman"><figcaption><p>Neue Tokenkonfiguration in Postman</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### Access Token generieren

<div data-with-frame="true"><figure><img src="https://2281246901-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlM26Mg6nljOOOe95HyIq%2Fuploads%2Fx0xbf48kdF1yESVRVgmU%2Fimage.png?alt=media&amp;token=791622b0-9bc0-4b1f-945f-e5c4bb206a1e" alt="Access-Token generieren" width="497"><figcaption><p>Access-Token generieren</p></figcaption></figure></div>

1. **Get New Access Token** auswählen.
2. Das Token wird abgerufen.
3. **Use Token** wird ausgewählt.
   {% endstep %}
   {% endstepper %}

### API-Abfragen durchführen

Nach erfolgreicher Authentifizierung können API-Abfragen über den Schnelleinstieg oder eine eigene Authentifizierung durchgeführt werden. Beispielabfragen sind in der Postman Collection enthalten.

<mark style="color:$info;">**Weitere Informationen:**</mark>\
[Documentation: v2 REST API Dokumentation](/verwaltungsoberflache/api-and-hooks/endpunkte/documentation-v2-rest-api-dokumentation.md) (Postman Collection + Environment)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpcenter.etron.info/verwaltungsoberflache/api-and-hooks/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.