Authentication API — Implementierung durch Kunden erforderlich

OpenAPI-Spezifikation

OpenAPI YAML herunterladen

Die Spezifikation kann im Swagger Editor geöffnet werden.

Basic Authentication für alle Endpunkte

Alle Endpunkte müssen HTTP Basic Authentication unterstützen.
Dies ist erforderlich, damit der Zugriff geschützt ist und PressMatrix die Identität der Client-Anwendung prüfen kann.

Jede API-Anfrage enthält einen Authorization-Header mit HTTP Basic Auth.
Zusätzlich enthält jede Anfrage einen Accept-Header mit application/json.
Wenn die Basic-Auth-Zugangsdaten fehlen oder falsch sind, müssen Ihre API-Endpunkte mit HTTP 401 Unauthorized antworten.
Der Kunde stellt PressMatrix Benutzername und Passwort für Basic Auth im Onboarding bereit.
In den cURL-Beispielen verwenden wir pressmatrix:"we'rereallysecure!" als Basic-Auth-Zugangsdaten.

Flowchart-Übersicht der Authentication API

Flowchart der Authentication API. Der /authenticate-Ablauf steht stellvertretend für die anderen Authorize-Endpunkte.

POST{auth-server-url}/pmx-api/v1/{profile_token}/authenticate

Authentication

Authentifiziert einen Abonnenten über Benutzername und Passwort.

Ablauf

Die Client-App oder der Browser sendet die Login-Daten des Benutzers (Benutzername und Passwort) an das Authentication-Backend des Kunden.
Das Authentication-Backend prüft, ob die Zugangsdaten gültig sind. Bei gültigen Daten gibt es ein Token zurück, sonst einen leeren String.
PressMatrix speichert dieses Token und sendet es bei allen folgenden API-Aufrufen des Benutzers mit.

Dieses Token dient als persistente Benutzer-ID und darf sich nicht ändern.

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
username
Type
string
Description
Benutzername (oder E-Mail-Adresse) des Abonnenten
Name
password
Type
string
Description
Passwort des Abonnenten

Antwortschema

Name
token
Type
string
Description
Nicht ablaufendes Authentication-Token. Leer, wenn der Login fehlgeschlagen ist.
Pattern: ^[A-Za-z0-9]+$

Anfrage

POST

/pmx-api/v1/{profile_token}/authenticate

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/authenticate \
  -u pressmatrix:"we'rereallysecure!"
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "secretpassword"
  }'

Erfolgsantwort

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Fehlerantwort

{
  "token": ""
}

POST{auth-server-url}/pmx-api/v1/:profile_token/authenticate_via_ticket

Ermöglicht PressMatrix, eine bestehende Benutzersitzung von einer externen Website über ein temporäres Session-Ticket zu übernehmen. Dies wird typischerweise für Single Sign-On (SSO) in Browser-Kiosken verwendet.

Ablauf

Der Benutzer meldet sich auf der Website des Publishers an, also im Authentifizierungssystem des Kunden.
Das System des Kunden erzeugt ein einmaliges session_ticket. Dieses Ticket:
- darf keine Punkte enthalten
- darf maximal 256 Zeichen lang sein

Der Benutzer wird an eine PressMatrix-Webhook-URL weitergeleitet:

https://your-browser-kiosk-domain/de/profiles/{{profile_token}}/users/ticket/{{session_ticket}}

Der Webhook löst einen Backend-Aufruf von PressMatrix an folgenden Endpunkt aus:
POST {auth-server-url}/pmx-api/v1/{profile_token}/authenticate_via_ticket
Der Authentifizierungsserver validiert das Ticket und gibt bei gültigem Ticket ein Token zurück, andernfalls einen leeren String.

Diese Methode ist eine vereinfachte Alternative zum /authenticate-Endpunkt und ermöglicht automatische Login-Flows, ohne Zugangsdaten erneut einzugeben. Sie ist auf browserbasierte Szenarien beschränkt.

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
ticket
Type
string
Description
Temporäres Session-Ticket. Es muss dem Ticket aus der Webhook-URL entsprechen. Pattern: ^[A-Za-z0-9]+$

Antwortschema

Name
token
Type
string
Description
Nicht ablaufendes Authentication-Token für zukünftige API-Anfragen. Wenn das Ticket ungültig oder unbekannt ist, wird ein leerer String zurückgegeben.

Anfrage

POST

/pmx-api/v1/{profile_token}/authenticate_via_ticket

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/authenticate_via_ticket \
  -u pressmatrix:"we'rereallysecure!"
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "ticket": "skF5N8MKcWY39L8Gnlnh4x6OO5KPdLkr9L7XBRMp"
  }'

Erfolgsantwort

{
  "token": "cbe45f4c-8a6d-4029-b74c-8c3182faa2bc"
}

Fehlerantwort

{
  "token": ""
}

POST{auth-server-url}/pmx-api/v1/:profile_token/authorize

Autorisierung (Ausgaben)

Prüft, ob ein authentifizierter Benutzer Zugriff auf ein bestimmtes Inhaltselement hat.

Ablauf

Der Kunde definiert Produkt-, Ausgabe- und Kategorieinformationen für jedes Publikationselement in der PressMatrix Workbench.
Wenn ein Benutzer Zugriff auf ein Element anfordert, sendet PressMatrix diese Details zusammen mit dem Token des Benutzers an den /authorize-Endpunkt des Kunden.
Das Backend des Kunden muss die Anfrage auswerten und entweder mit granted: true oder granted: false antworten.

Der Kunde ist für die Implementierung dieses Endpunkts verantwortlich und kann eigene interne Regeln oder Zuordnungen definieren. Die Entscheidung muss jedoch ausschließlich auf den Feldern der Anfrage basieren.

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
token
Type
string
Description
Das persistente Benutzer-Token aus /authenticate oder /authenticate_via_ticket
Name
issue_name
Type
string
Description
Anzeigename der Ausgabe, auf die zugegriffen werden soll
Name
issue_date
Type
string
Description
Veröffentlichungsdatum der Ausgabe im Format YYYY-MM-DD
Name
category_name
Type
string
Description
Anzeigename der Kategorie, zu der die Ausgabe gehört
Name
category_ids
Type
string
Description
Kommagetrennte Liste aller Kategorie-IDs
Name
product_id_apple
Type
string
Description
Apple product ID
Name
product_id_google
Type
string
Description
Google product ID
Name
product_id_amazon
Type
string
Description
Amazon product ID
Name
product_id_external
Type
string
Description
Externe kundenspezifische Product ID

Antwortschema

Name
granted
Type
boolean
Description
Gibt an, ob der Zugriff gewährt (true) oder verweigert (false) wird.

Anfrage

POST

/pmx-api/v1/{profile_token}/authorize

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/authorize \
  -u pressmatrix:"we'rereallysecure!"
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "user_token",
    "issue_name": "Sample Issue May 2014",
    "issue_date": "2014-05-01",
    "category_name": "Sample Category",
    "category_ids": "20924,20925",
    "product_id_apple": "sample_issue_2014_05",
    "product_id_google": "sample_issue_2014_05",
    "product_id_amazon": "sample_issue_2014_05",
    "product_id_external": "sample_id_1,sample_id_2"
  }'

Zugriff gewährt

{
  "granted": true
}

Zugriff verweigert

{
  "granted": false
}

POST{auth-server-url}/pmx-api/v1/:profile_token/authorize_download

(Optional) Autorisierung (Download)

Prüft, ob ein authentifizierter Benutzer Zugriff auf einen bestimmten Download hat.

Ablauf

...tbd...

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
token
Type
string
Description
Das persistente Benutzer-Token aus /authenticate oder /authenticate_via_ticket
Name
name
Type
string
Description
Anzeigename des Downloads, auf den zugegriffen werden soll
Name
date
Type
string
Description
Veröffentlichungsdatum der Ausgabe im Format YYYY-MM-DD
Name
category_name
Type
string
Description
Anzeigename der Kategorie, zu der die Ausgabe gehört
Name
category_ids
Type
string
Description
Kommagetrennte Liste aller Kategorie-IDs
Name
product_id_external
Type
string
Description
Externe kundenspezifische Product ID

Antwortschema

Name
granted
Type
boolean
Description
Gibt an, ob der Zugriff gewährt (true) oder verweigert (false) wird.

Anfrage

POST

/pmx-api/v1/{profile_token}/authorize_download

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/authorize_download \
  -u pressmatrix:"we'rereallysecure!"
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "user_token",
    "name": "Sample Issue May 2014",
    "date": "2014-05-01",
    "category_name": "Sample Category",
    "category_ids": "20924,20925",
    "product_id_external": "sample_id_1,sample_id_2"
  }'

Zugriff gewährt

{
  "granted": true
}

Zugriff verweigert

{
  "granted": false
}

POST{auth-server-url}/pmx-api/v1/:profile_token/authorize_chatbot

(Optional) Autorisierung (Chatbot)

Prüft, ob ein authentifizierter Benutzer Zugriff auf den Chatbot hat.

Ablauf

...tbd...

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
token
Type
string
Description
Das persistente Benutzer-Token aus /authenticate oder /authenticate_via_ticket
Name
name
Type
string
Description
Anzeigename des Chatbots
Name
uuid
Type
string
Description
Chatbot-UUID als eindeutige Kennung der Chatbot-Instanz
Name
product_id_external
Type
string
Description
Externe kundenspezifische Product ID

Antwortschema

Name
granted
Type
boolean
Description
Gibt an, ob der Zugriff gewährt (true) oder verweigert (false) wird.

Anfrage

POST

/pmx-api/v1/{profile_token}/authorize_chatbot

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/authorize_chatbot \
-u pressmatrix:"we'rereallysecure!" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "token": "ff78bf90826c4f48ce3e",
  "name": "Chatty",
  "uuid": "4ea94fb1-7d9d-4e6d-ab57-90d7e7b31b2e",
  "product_id_external": "com.pressmatrix.staging.chatbot.001"
}'

Zugriff gewährt

{
  "granted": true
}

Zugriff verweigert

{
  "granted": false
}

POST{auth-server-url}/pmx-api/v1/:profile_token/authorize_article

(Optional) Autorisierung (Artikel)

Prüft, ob ein authentifizierter Benutzer Zugriff auf einen bestimmten Artikel hat.

Ablauf

...tbd...

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
token
Type
string
Description
Das persistente Benutzer-Token aus /authenticate oder /authenticate_via_ticket
Name
name
Type
string
Description
Anzeigename des Artikels, auf den zugegriffen werden soll
Name
date
Type
string
Description
Veröffentlichungsdatum des Artikels im Format YYYY-MM-DD
Name
category_name
Type
string
Description
Anzeigename der Kategorie, zu der die Ausgabe gehört
Name
category_ids
Type
string
Description
Kommagetrennte Liste aller Kategorie-IDs
Name
product_id_apple
Type
string
Description
Apple product ID
Name
product_id_google
Type
string
Description
Google product ID
Name
product_id_amazon
Type
string
Description
Amazon product ID
Name
product_id_external
Type
string
Description
Externe kundenspezifische Product ID

Antwortschema

Name
granted
Type
boolean
Description
Gibt an, ob der Zugriff gewährt (true) oder verweigert (false) wird.

Anfrage

POST

/pmx-api/v1/{profile_token}/authorize_article

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/authorize_article \
  -u pressmatrix:"we'rereallysecure!"
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "user_token",
    "name": "Article name",
    "date": "2014-05-01",
    "category_name": "Sample Category",
    "category_ids": "20924,20925",
    "product_id_apple": "sample_issue_2014_05",
    "product_id_google": "sample_issue_2014_05",
    "product_id_amazon": "sample_issue_2014_05",
    "product_id_external": "sample_id_1,sample_id_2"
  }'

Zugriff gewährt

{
  "granted": true
}

Zugriff verweigert

{
  "granted": false
}

POST{auth-server-url}/pmx-api/v1/:profile_token/issues

(Optional) Ausgaben

Diese Funktion ist optional und muss explizit durch PressMatrix aktiviert werden. Wenn sie aktiviert ist, können Benutzer alle Ausgaben sehen, auf die sie gemäß den in der PressMatrix Workbench konfigurierten Product IDs Zugriff haben.

Gibt eine Liste von Product IDs zurück, die allen Ausgaben entsprechen, auf die der authentifizierte Benutzer zugreifen darf.

Jede zurückgegebene Product ID muss einem der konfigurierten Identifier entsprechen:

product_id_apple
product_id_google
product_id_amazon (deprecated)
product_id_external

Der Kunde kann unterschiedliche Product-ID-Typen gemischt zurückgeben. PressMatrix ordnet diese IDs automatisch den richtigen Ausgaben zu.

Ablauf

PressMatrix sendet das persistente Token des Benutzers an den /issues-Endpunkt des Kunden.
Das Backend des Kunden prüft, welche Ausgaben dem Benutzer gehören.
Der Endpunkt gibt ein flaches Array von Product IDs zurück.

Regeln

Die Reihenfolge ist nicht relevant.
Duplikate dürfen nicht zurückgegeben werden.
Pro Ausgabe muss mindestens eine unterstützte Product ID zurückgegeben werden, damit sie sichtbar ist.

Parameter

Name
profile_token
Type
string
Description
Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Body

Name
token
Type
string
Description
Das persistente Benutzer-Token aus /authenticate oder /authenticate_via_ticket

Antwortschema

Name
issues
Type
array
Description
Array von Product IDs, die die für den Benutzer zugänglichen Ausgaben repräsentieren

Anfrage

POST

/pmx-api/v1/{profile_token}/issues

curl -X POST https://{auth-server-url}/pmx-api/v1/{profile_token}/issues \
  -u pressmatrix:"we'rereallysecure!" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "user_token_12345"
  }'

Beispielantwort mit gemischten IDs

{
  "issues": [
    "sample_issue_2024_01",            // external product ID
    "com.publisher.issue202402",       // apple product ID
    "com.publisher.issues.202403"       // google product ID
  ]
}

Beispielantwort ohne Ausgaben

{
  "issues": []
}

Authentication API — Implementierung durch Kunden erforderlich

Basierend auf AWS Lambda, DynamoDB und API Gateway (serverless), geschrieben in JS ES Modules.

Ablauf

Parameter

Anfrage-Body

Antwortschema

Anfrage

Erfolgsantwort

Fehlerantwort

Ablauf

Parameter

Anfrage-Body

Antwortschema

Anfrage

Erfolgsantwort

Fehlerantwort

Ablauf

Parameter

Anfrage-Body

Antwortschema

Anfrage

Zugriff gewährt

Zugriff verweigert

Ablauf

Parameter

Anfrage-Body

Antwortschema

Anfrage

Zugriff gewährt

Zugriff verweigert

Ablauf

Parameter

Anfrage-Body

Antwortschema

Anfrage

Zugriff gewährt

Zugriff verweigert

Ablauf

Parameter

Anfrage-Body

Antwortschema

Anfrage

Zugriff gewährt

Zugriff verweigert

Ablauf

Regeln

Parameter

Anfrage-Body

Antwortschema

Anfrage

Beispielantwort mit gemischten IDs

Beispielantwort ohne Ausgaben