PressMatrix API docs

Authentication API (OIDC) — Implementierung durch Kunden erforderlich

OpenAPI-Spezifikation

OpenAPI YAML herunterladen

Die Spezifikation kann im Swagger Editor geöffnet werden.

Bereitstellung durch den Kunden

Diese API wird nicht von PressMatrix bereitgestellt oder betrieben. Der Kunde muss die beschriebenen Endpunkte in seiner eigenen Infrastruktur implementieren und erreichbar machen.

Aktuell unterstützte OIDC Provider

PressMatrix unterstützt für diese OIDC-Integration aktuell den internen Provider PX-User, Auth0 und Keycloak. Weitere Provider sind in Vorbereitung und können auf Kundenanfrage ggf. eingebunden werden. Stimmen Sie nicht aufgeführte Provider vor der Implementierung mit PressMatrix ab.

OIDC Access-Token-Authentifizierung für alle Endpunkte

Alle Endpunkte müssen das Access Token validieren, das im Header Authorization: Bearer {ACCESS_TOKEN} übertragen wird. Der konfigurierte OIDC Provider stellt dieses Token aus; Bearer ist das HTTP-Authorization-Schema, nicht das Token-Format. Es bedeutet hier, dass das Token selbst der Nachweis für die Anfrage ist. PressMatrix sendet keine Benutzername-/Passwort-Zugangsdaten an diese API. Die Endbenutzer-Authentifizierung findet vorher beim Identity Provider (IdP) des Kunden statt.

  • Jede API-Anfrage enthält einen Authorization-Header mit Bearer {ACCESS_TOKEN}.
  • Jede API-Anfrage enthält einen Accept-Header mit application/json.
  • PressMatrix kann zusätzlich das ursprüngliche OpenID Connect ID Token im optionalen OIDC-ID-Token-Header weiterleiten.
  • Wenn das Bearer Token fehlt, fehlerhaft, abgelaufen oder ungültig ist, müssen Ihre API-Endpunkte mit HTTP 401 Unauthorized antworten.
  • Wenn das Token gültig ist, der Zugriff aber durch fachliche Regeln verweigert wird, antworten Sie mit HTTP 200 und granted: false.
  • Das Token-Format ist durch diesen Vertrag bewusst nicht festgelegt. Der Kunde kann JWT Access Tokens oder opaque Access Tokens verwenden.

Flowchart-Übersicht der Authentication API (OIDC)

Flowchart der Authentication API (OIDC). Der /authorize-Ablauf steht stellvertretend für die anderen Authorize-Endpunkte.

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

Autorisierung (Ausgaben)

Prüft, ob ein upstream authentifizierter Benutzer Zugriff auf eine bestimmte Ausgabe hat.

Ablauf

  1. Der Benutzer authentifiziert sich beim Identity Provider des Kunden.
  2. PressMatrix erhält oder übernimmt das Access Token des Benutzers vom konfigurierten OIDC Provider.
  3. Wenn der Benutzer eine Ausgabe anfragt, sendet PressMatrix das Bearer Token und die Ausgabenmetadaten an den /authorize-Endpunkt des Kunden.
  4. Das Backend des Kunden validiert das Bearer Token und wertet die fachlichen Regeln für die angefragte Ausgabe aus.
  5. Der Endpunkt antwortet mit granted: true, granted: false oder HTTP 401, wenn das Token ungültig ist.

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

Parameter

  • Name
    profile_token
    Type
    string
    Description

    Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Header

  • Name
    Authorization
    Type
    string
    Description

    Access Token, das als Authorization: Bearer {ACCESS_TOKEN} gesendet wird und den upstream authentifizierten Benutzer repräsentiert

  • Name
    OIDC-ID-Token
    Type
    string
    Description

    Optionales OpenID Connect ID Token, das bei Bedarf und Verfügbarkeit an die Kundenintegration weitergeleitet wird

Anfrage-Body

  • 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/v2/{profile_token}/authorize
curl -X POST https://{auth-server-url}/pmx-api/v2/{profile_token}/authorize \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "OIDC-ID-Token: {OIDC_ID_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "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/v2/{profile_token}/authorize_download

(Optional) Autorisierung (Download)

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

Ablauf

  1. Der Benutzer fragt einen geschützten Download an.
  2. PressMatrix sendet das Bearer Token und die Download-Metadaten an den /authorize_download-Endpunkt des Kunden.
  3. Das Backend des Kunden validiert das Bearer Token und prüft, ob der Benutzer auf den Download zugreifen darf.
  4. Der Endpunkt antwortet mit granted: true, granted: false oder HTTP 401, wenn das Token ungültig ist.

Parameter

  • Name
    profile_token
    Type
    string
    Description

    Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Header

  • Name
    Authorization
    Type
    string
    Description

    Access Token, das als Authorization: Bearer {ACCESS_TOKEN} gesendet wird und den upstream authentifizierten Benutzer repräsentiert

  • Name
    OIDC-ID-Token
    Type
    string
    Description

    Optionales OpenID Connect ID Token, das bei Bedarf und Verfügbarkeit an die Kundenintegration weitergeleitet wird

Anfrage-Body

  • Name
    name
    Type
    string
    Description

    Anzeigename des Downloads, auf den zugegriffen werden soll

  • Name
    date
    Type
    string
    Description

    Veröffentlichungsdatum des Downloads im Format YYYY-MM-DD

  • Name
    category_name
    Type
    string
    Description

    Anzeigename der Kategorie

  • 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/v2/{profile_token}/authorize_download
curl -X POST https://{auth-server-url}/pmx-api/v2/{profile_token}/authorize_download \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Sample Download 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/v2/{profile_token}/authorize_chatbot

(Optional) Autorisierung (Chatbot)

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

Ablauf

  1. Der Benutzer fragt Zugriff auf einen Chatbot an.
  2. PressMatrix sendet das Bearer Token und die Chatbot-Metadaten an den /authorize_chatbot-Endpunkt des Kunden.
  3. Das Backend des Kunden validiert das Bearer Token und prüft, ob der Benutzer auf den Chatbot zugreifen darf.
  4. Der Endpunkt antwortet mit granted: true, granted: false oder HTTP 401, wenn das Token ungültig ist.

Parameter

  • Name
    profile_token
    Type
    string
    Description

    Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Header

  • Name
    Authorization
    Type
    string
    Description

    Access Token, das als Authorization: Bearer {ACCESS_TOKEN} gesendet wird und den upstream authentifizierten Benutzer repräsentiert

  • Name
    OIDC-ID-Token
    Type
    string
    Description

    Optionales OpenID Connect ID Token, das bei Bedarf und Verfügbarkeit an die Kundenintegration weitergeleitet wird

Anfrage-Body

  • 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/v2/{profile_token}/authorize_chatbot
curl -X POST https://{auth-server-url}/pmx-api/v2/{profile_token}/authorize_chatbot \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "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/v2/{profile_token}/authorize_article

(Optional) Autorisierung (Artikel)

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

Ablauf

  1. Der Benutzer fragt einen geschützten Artikel an.
  2. PressMatrix sendet das Bearer Token und die Artikelmetadaten an den /authorize_article-Endpunkt des Kunden.
  3. Das Backend des Kunden validiert das Bearer Token und prüft, ob der Benutzer auf den Artikel zugreifen darf.
  4. Der Endpunkt antwortet mit granted: true, granted: false oder HTTP 401, wenn das Token ungültig ist.

Parameter

  • Name
    profile_token
    Type
    string
    Description

    Das eindeutige Profile-Token der Kundenpublikation

Anfrage-Header

  • Name
    Authorization
    Type
    string
    Description

    Access Token, das als Authorization: Bearer {ACCESS_TOKEN} gesendet wird und den upstream authentifizierten Benutzer repräsentiert

  • Name
    OIDC-ID-Token
    Type
    string
    Description

    Optionales OpenID Connect ID Token, das bei Bedarf und Verfügbarkeit an die Kundenintegration weitergeleitet wird

Anfrage-Body

  • 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 der Artikel 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/v2/{profile_token}/authorize_article
curl -X POST https://{auth-server-url}/pmx-api/v2/{profile_token}/authorize_article \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "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/v2/{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

  1. PressMatrix sendet das Bearer Token an den /issues-Endpunkt des Kunden.
  2. Das Backend des Kunden validiert das Bearer Token.
  3. Das Backend des Kunden prüft, welche Ausgaben dem authentifizierten Benutzer gehören.
  4. Der Endpunkt gibt ein flaches Array von Product IDs zurück oder HTTP 401, wenn das Token ungültig ist.

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

  • Name
    Authorization
    Type
    string
    Description

    Access Token, das als Authorization: Bearer {ACCESS_TOKEN} gesendet wird und den upstream authentifizierten Benutzer repräsentiert

  • Name
    OIDC-ID-Token
    Type
    string
    Description

    Optionales OpenID Connect ID Token, das bei Bedarf und Verfügbarkeit an die Kundenintegration weitergeleitet wird

Anfrage-Body

  • Name
    -
    Type
    object
    Description

    Es sind keine fachlichen Felder erforderlich. Der authentifizierte Benutzer wird aus dem Bearer Token abgeleitet.

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/v2/{profile_token}/issues
curl -X POST https://{auth-server-url}/pmx-api/v2/{profile_token}/issues \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{}'

Beispielantwort mit gemischten IDs

{
  "issues": [
    "sample_issue_2024_01",
    "com.publisher.issue202402",
    "com.publisher.issues.202403"
  ]
}

Beispielantwort ohne Ausgaben

{
  "issues": []
}