Authentication API (OIDC) — Customer Implementation Required

OpenAPI Specification

Download OpenAPI YAML

You can view the spec with Swagger Editor.

Provided by the Customer

This API is not provided or operated by PressMatrix. The customer must implement and expose the described endpoints in their own infrastructure.

Currently Supported OIDC Providers

PressMatrix currently supports the internal PX-User provider, Auth0, and Keycloak for this OIDC integration. Additional providers are in preparation and may be added for customer projects on request. Confirm unsupported providers with PressMatrix before implementation.

OIDC Access Token Authentication for All Endpoints

All endpoints must validate the access token sent in the Authorization: Bearer {ACCESS_TOKEN} header. The configured OIDC provider issues this token; Bearer is the HTTP authorization scheme, not the token format. It means the token itself is the credential for the request. PressMatrix does not send username and password credentials to this API. End-user authentication happens upstream against the customer's Identity Provider (IdP).

Every API request includes an Authorization header with Bearer {ACCESS_TOKEN}.
Every API request includes an Accept header with application/json.
PressMatrix may additionally forward the original OpenID Connect ID Token in the optional OIDC-ID-Token header.
If the bearer token is missing, malformed, expired, or invalid, your API endpoints must respond with HTTP 401 Unauthorized.
If the token is valid but access is denied by business rules, respond with HTTP 200 and granted: false.
Token format is intentionally not fixed by this contract. The customer may use JWT access tokens or opaque access tokens.

Flowchart Overview of Authentication API (OIDC)

Flowchart of Authentication API (OIDC). The /authorize flow represents all other authorize endpoints.

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

Authorization (Issues)

Checks if an upstream-authenticated user has access to a specific issue.

Workflow

The user authenticates against the customer's Identity Provider.
PressMatrix receives or is provided with the user's access token from the configured OIDC provider.
When the user requests an issue, PressMatrix sends the bearer token and issue metadata to the customer's /authorize endpoint.
The customer's backend validates the bearer token and evaluates the business rules for the requested issue.
The endpoint responds with granted: true, granted: false, or HTTP 401 if the token is invalid.

The customer is responsible for implementing this endpoint and may define internal rules or mappings, but the decision must be based on the authenticated user and the fields provided in the request.

Parameters

Name
profile_token
Type
string
Description
The unique profile token for the customer's publication

Request Headers

Name
Authorization
Type
string
Description
Access token sent as Authorization: Bearer {ACCESS_TOKEN}; represents the upstream-authenticated user
Name
OIDC-ID-Token
Type
string
Description
Optional OpenID Connect ID Token forwarded when available and required by the customer integration

Request Body

Name
issue_name
Type
string
Description
Display name of the issue to access
Name
issue_date
Type
string
Description
Publication date of the issue (format: YYYY-MM-DD)
Name
category_name
Type
string
Description
Display name of the category the issue belongs to
Name
category_ids
Type
string
Description
Comma-separated list of all category 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
External (custom) product ID

Response Schema

Name
granted
Type
boolean
Description
Whether access is granted (true) or denied (false).

Request

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"
  }'

Access Granted

{
  "granted": true
}

Access Denied

{
  "granted": false
}

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

(Optional) Authorization (Download)

Checks if an upstream-authenticated user has access to a specific download.

Workflow

The user requests a protected download.
PressMatrix sends the bearer token and download metadata to the customer's /authorize_download endpoint.
The customer's backend validates the bearer token and evaluates whether the user may access the download.
The endpoint responds with granted: true, granted: false, or HTTP 401 if the token is invalid.

Parameters

Name
profile_token
Type
string
Description
The unique profile token for the customer's publication

Request Headers

Name
Authorization
Type
string
Description
Access token sent as Authorization: Bearer {ACCESS_TOKEN}; represents the upstream-authenticated user
Name
OIDC-ID-Token
Type
string
Description
Optional OpenID Connect ID Token forwarded when available and required by the customer integration

Request Body

Name
name
Type
string
Description
Display name of the download to access
Name
date
Type
string
Description
Publication date of the download (format: YYYY-MM-DD)
Name
category_name
Type
string
Description
Display name of the category
Name
category_ids
Type
string
Description
Comma-separated list of all category IDs
Name
product_id_external
Type
string
Description
External (custom) product ID

Response Schema

Name
granted
Type
boolean
Description
Whether access is granted (true) or denied (false).

Request

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"
  }'

Access Granted

{
  "granted": true
}

Access Denied

{
  "granted": false
}

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

(Optional) Authorization (ChatBot)

Checks if an upstream-authenticated user has access to the chatbot.

Workflow

The user requests access to a chatbot.
PressMatrix sends the bearer token and chatbot metadata to the customer's /authorize_chatbot endpoint.
The customer's backend validates the bearer token and evaluates whether the user may access the chatbot.
The endpoint responds with granted: true, granted: false, or HTTP 401 if the token is invalid.

Parameters

Name
profile_token
Type
string
Description
The unique profile token for the customer's publication

Request Headers

Name
Authorization
Type
string
Description
Access token sent as Authorization: Bearer {ACCESS_TOKEN}; represents the upstream-authenticated user
Name
OIDC-ID-Token
Type
string
Description
Optional OpenID Connect ID Token forwarded when available and required by the customer integration

Request Body

Name
name
Type
string
Description
Display name of the chatbot
Name
uuid
Type
string
Description
Chatbot UUID (unique identifier for the chatbot instance)
Name
product_id_external
Type
string
Description
External (custom) product ID

Response Schema

Name
granted
Type
boolean
Description
Whether access is granted (true) or denied (false).

Request

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"
  }'

Access Granted

{
  "granted": true
}

Access Denied

{
  "granted": false
}

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

(Optional) Authorization (Article)

Checks if an upstream-authenticated user has access to a specific article.

Workflow

The user requests a protected article.
PressMatrix sends the bearer token and article metadata to the customer's /authorize_article endpoint.
The customer's backend validates the bearer token and evaluates whether the user may access the article.
The endpoint responds with granted: true, granted: false, or HTTP 401 if the token is invalid.

Parameters

Name
profile_token
Type
string
Description
The unique profile token for the customer's publication

Request Headers

Name
Authorization
Type
string
Description
Access token sent as Authorization: Bearer {ACCESS_TOKEN}; represents the upstream-authenticated user
Name
OIDC-ID-Token
Type
string
Description
Optional OpenID Connect ID Token forwarded when available and required by the customer integration

Request Body

Name
name
Type
string
Description
Display name of the article to access
Name
date
Type
string
Description
Publication date of the article (format: YYYY-MM-DD)
Name
category_name
Type
string
Description
Display name of the category the article belongs to
Name
category_ids
Type
string
Description
Comma-separated list of all category 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
External (custom) product ID

Response Schema

Name
granted
Type
boolean
Description
Whether access is granted (true) or denied (false).

Request

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"
  }'

Access Granted

{
  "granted": true
}

Access Denied

{
  "granted": false
}

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

(Optional) Issues

This feature is optional and must be explicitly enabled by PressMatrix. When enabled, users can see all issues they are entitled to access based on the product IDs configured in the PressMatrix Workbench.

Returns a list of product IDs corresponding to all issues the authenticated user is allowed to access.

Each returned product ID must match one of the configured identifiers:

product_id_apple
product_id_google
product_id_amazon (deprecated)
product_id_external

The customer can return mixed product ID types. PressMatrix automatically maps these IDs to the correct issues.

Workflow

PressMatrix sends the bearer token to the customer's /issues endpoint.
The customer's backend validates the bearer token.
The customer's backend checks which issues the authenticated user owns.
The endpoint returns a flat array of product IDs, or HTTP 401 if the token is invalid.

Rules

Order does not matter.
Duplicates must not be returned.
At least one supported product ID per issue must be returned for it to be visible.

Parameters

Name
profile_token
Type
string
Description
The unique profile token for the customer's publication

Request Headers

Name
Authorization
Type
string
Description
Access token sent as Authorization: Bearer {ACCESS_TOKEN}; represents the upstream-authenticated user
Name
OIDC-ID-Token
Type
string
Description
Optional OpenID Connect ID Token forwarded when available and required by the customer integration

Request Body

Name
-
Type
object
Description
No business fields are required. The authenticated user is derived from the bearer token.

Response Schema

Name
issues
Type
array
Description
Array of product IDs representing the user's accessible issues

Request

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 '{}'

Sample Response (Mixed IDs)

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

Sample Response (Empty)

{
  "issues": []
}