openapi: 3.0.3
info:
  title: PressMatrix Authentication API
  description: |
    Customer Implementation Required API for PressMatrix authentication and authorization.
    
    All endpoints require HTTP Basic Authentication and must include:
    - Authorization header with Basic Auth credentials
    - Accept header with application/json
    
    **Important**: This API must be implemented by the customer and provided to PressMatrix during onboarding.
    ## Profile Token
    Every API call requires a profile_token in the URL. This token uniquely identifies your publication or tenant. 
    
    The profile token will be provided during onboarding or can be found in your browser client url:
    
    https://bc.pressmatrix.com/de/profiles/**<profile_token>**/editions.
  version: 1.0.0
  contact:
    name: PressMatrix Api Doc
    url: https://www.docs.pressmatrix.com/authentication-api
servers:
  - url: https://{auth-server-url}/pmx-api/v1/{profile-token}
    description: Customer's authentication server
    variables:
      auth-server-url:
        default: api.your-domain.com
        description: Customer's authentication server URL
      profile-token:
        default: a1b2c3d4e5f6
        description: This token uniquely identifies your publication
security:
  - basicAuth: []
paths:
  /{profile_token}/authenticate:
    post:
      tags:
        - Authentication
      summary: Authenticate subscriber
      description: |
        Authenticates a subscriber by their username and password.
        Returns a non-expiring token that serves as the persistent user ID.
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateRequest'
            example:
              username: user@example.com
              password: secretpassword
      responses:
        '200':
          description: Authentication attempt completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
              examples:
                success:
                  summary: Successful authentication
                  value:
                    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
                failure:
                  summary: Failed authentication
                  value:
                    token: ""
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

  /{profile_token}/authenticate_via_ticket:
    post:
      tags:
        - Authentication (optional)
      summary: Authenticate via session ticket
      description: |
        Authenticates using a temporary session ticket for Single Sign-On (SSO) scenarios.
        Typically used in browser kiosks where users are redirected from the publisher's website.
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateViaTicketRequest'
            example:
              ticket: "skF5N8MKcWY39L8Gnlnh4x6OO5KPdLkr9L7XBRMp"
      responses:
        '200':
          description: Ticket authentication attempt completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
              examples:
                success:
                  summary: Valid ticket
                  value:
                    token: "cbe45f4c-8a6d-4029-b74c-8c3182faa2bc"
                failure:
                  summary: Invalid ticket
                  value:
                    token: ""
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

  /{profile_token}/authorize:
    post:
      tags:
        - Authorization
      summary: Authorize access to content issues
      description: |
        Checks if an authenticated user has access to a specific content item/issue.
        The customer must implement authorization logic based on the provided parameters.
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeRequest'
            example:
              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"
      responses:
        '200':
          description: Authorization decision completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
              examples:
                granted:
                  summary: Access granted
                  value:
                    granted: true
                denied:
                  summary: Access denied
                  value:
                    granted: false
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

  /{profile_token}/authorize_download:
    post:
      tags:
        - Authorization (Optional)
      summary: Authorize access to downloads (Preview)
      description: |
        Checks if an authenticated user has access to a specific download.
        
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeDownloadRequest'
            example:
              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"
      responses:
        '200':
          description: Download authorization decision completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
              examples:
                granted:
                  summary: Access granted
                  value:
                    granted: true
                denied:
                  summary: Access denied
                  value:
                    granted: false
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

  /{profile_token}/authorize_chatbot:
    post:
      tags:
        - Authorization (Optional)
      summary: Authorize access to chatbot (Preview)
      description: |
        Checks if an authenticated user has access to the chatbot.
        
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeChatbotRequest'
            example:
              token: "ff78bf90826c4f48ce3e"
              name: "Chatty"
              uuid: "4ea94fb1-7d9d-4e6d-ab57-90d7e7b31b2e"
              product_id_external: "com.pressmatrix.staging.chatbot.001"
      responses:
        '200':
          description: Chatbot authorization decision completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
              examples:
                granted:
                  summary: Access granted
                  value:
                    granted: true
                denied:
                  summary: Access denied
                  value:
                    granted: false
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

  /{profile_token}/authorize_article:
    post:
      tags:
        - Authorization (Optional)
      summary: Authorize access to articles (Preview)
      description: |
        Checks if an authenticated user has access to a specific article.
        
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeArticleRequest'
            example:
              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"
      responses:
        '200':
          description: Article authorization decision completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
              examples:
                granted:
                  summary: Access granted
                  value:
                    granted: true
                denied:
                  summary: Access denied
                  value:
                    granted: false
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

  /{profile_token}/issues:
    post:
      tags:
        - Optional Features
      summary: Get accessible issues (Optional)
      description: |
        **Optional Feature**: Returns a list of issue product IDs accessible to the authenticated user.
        This feature must be specifically activated by PressMatrix and is disabled by default.
        
        The returned issue IDs must match exactly with those defined in PressMatrix Workbench.
      parameters:
        - $ref: '#/components/parameters/ProfileToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssuesRequest'
            example:
              token: "user_token"
      responses:
        '200':
          description: List of accessible issues returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuesResponse'
              example:
                issues:
                  - "sample_issue_2014_01"
                  - "sample_issue_2014_02"
                  - "sample_issue_2014_03"
        '401':
          description: Unauthorized - Invalid or missing Basic Auth credentials.
        '400':
          description: Bad Request - Invalid request body or missing required parameters.
        '500':
          description: Internal Server Error - An error occurred on the server.

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic Authentication is required for all endpoints.
        Credentials must be provided by the customer during onboarding.

  parameters:
    ProfileToken:
      name: profile_token
      in: path
      required: true
      description: |
        The unique profile token for the customer's publication.
        This token is provided during onboarding by PressMatrix.
        
        Example URL: https://bc.pressmatrix.com/de/profiles/**<profile_token>**/editions.
      schema:
        type: string
        pattern: '^[A-Za-z0-9_-]+$'
        example: "a1b2c3d4e5f6"

  schemas:
    AuthenticateRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: Username or email of the subscriber
          example: "user@example.com"
        password:
          type: string
          description: Password of the subscriber
          format: password
          example: "secretpassword"

    AuthenticateViaTicketRequest:
      type: object
      required:
        - ticket
      properties:
        ticket:
          type: string
          description: |
            Temporary session ticket for SSO authentication.
            Must not contain dots and must not exceed 256 characters.
          pattern: '^[A-Za-z0-9]+$'
          maxLength: 256
          example: "skF5N8MKcWY39L8Gnlnh4x6OO5KPdLkr9L7XBRMp"

    AuthenticateResponse:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: |
            Non-expiring authentication token. Empty string if authentication failed.
            This token acts as the persistent user ID and must not change over time.
          pattern: '^[A-Za-z0-9]*$'
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

    AuthorizeRequest:
      type: object
      required:
        - token
        - issue_name
        - issue_date
        - category_name
        - category_ids
        - product_id_apple
        - product_id_google
        - product_id_amazon
        - product_id_external
      properties:
        token:
          type: string
          description: The persistent user token from authentication
          example: "user_token"
        issue_name:
          type: string
          description: Display name of the issue to access
          example: "Sample Issue May 2014"
        issue_date:
          type: string
          format: date
          description: Publication date of the issue (YYYY-MM-DD)
          example: "2014-05-01"
        category_name:
          type: string
          description: Display name of the category the issue belongs to
          example: "Sample Category"
        category_ids:
          type: string
          description: Comma-separated list of all category IDs
          example: "20924,20925"
        product_id_apple:
          type: string
          description: Apple product ID
          example: "sample_issue_2014_05"
        product_id_google:
          type: string
          description: Google product ID
          example: "sample_issue_2014_05"
        product_id_amazon:
          type: string
          description: Amazon product ID
          example: "sample_issue_2014_05"
        product_id_external:
          type: string
          description: External (custom) product ID
          example: "sample_id_1,sample_id_2"

    AuthorizeDownloadRequest:
      type: object
      required:
        - token
        - name
        - date
        - category_name
        - category_ids
        - product_id_external
      properties:
        token:
          type: string
          description: The persistent user token from authentication
          example: "user_token"
        name:
          type: string
          description: Display name of the download to access
          example: "Sample Download May 2014"
        date:
          type: string
          format: date
          description: Publication date (YYYY-MM-DD)
          example: "2014-05-01"
        category_name:
          type: string
          description: Display name of the category
          example: "Sample Category"
        category_ids:
          type: string
          description: Comma-separated list of all category IDs
          example: "20924,20925"
        product_id_external:
          type: string
          description: External (custom) product ID
          example: "sample_id_1,sample_id_2"

    AuthorizeChatbotRequest:
      type: object
      required:
        - token
        - name
        - uuid
        - product_id_external
      properties:
        token:
          type: string
          description: The persistent user token from authentication
          example: "ff78bf90826c4f48ce3e"
        name:
          type: string
          description: Display name of the chatbot
          example: "Chatty"
        uuid:
          type: string
          format: uuid
          description: Chatbot UUID (unique identifier for the chatbot instance)
          example: "4ea94fb1-7d9d-4e6d-ab57-90d7e7b31b2e"
        product_id_external:
          type: string
          description: External (custom) product ID
          example: "com.pressmatrix.staging.chatbot.001"

    AuthorizeArticleRequest:
      type: object
      required:
        - token
        - name
        - date
        - category_name
        - category_ids
        - product_id_apple
        - product_id_google
        - product_id_amazon
        - product_id_external
      properties:
        token:
          type: string
          description: The persistent user token from authentication
          example: "user_token"
        name:
          type: string
          description: Display name of the article to access
          example: "Article name"
        date:
          type: string
          format: date
          description: Publication date of the article (YYYY-MM-DD)
          example: "2014-05-01"
        category_name:
          type: string
          description: Display name of the category
          example: "Sample Category"
        category_ids:
          type: string
          description: Comma-separated list of all category IDs
          example: "20924,20925"
        product_id_apple:
          type: string
          description: Apple product ID
          example: "sample_issue_2014_05"
        product_id_google:
          type: string
          description: Google product ID
          example: "sample_issue_2014_05"
        product_id_amazon:
          type: string
          description: Amazon product ID
          example: "sample_issue_2014_05"
        product_id_external:
          type: string
          description: External (custom) product ID
          example: "sample_id_1,sample_id_2"

    AuthorizeResponse:
      type: object
      required:
        - granted
      properties:
        granted:
          type: boolean
          description: Whether access is granted (true) or denied (false)
          example: true

    IssuesRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: The persistent user token from authentication
          example: "user_token"

    IssuesResponse:
      type: object
      required:
        - issues
      properties:
        issues:
          type: array
          description: Array of product IDs that represent the accessible issues
          items:
            type: string
            description: Product ID of an accessible issue
          example:
            - "sample_issue_2014_01"
            - "sample_issue_2014_02"
            - "sample_issue_2014_03"
tags:
  - name: Authentication
    description: Endpoints for user authentication
  - name: Authentication (optional)
    description: Optional endpoints for user authentication
  - name: Authorization
    description: Endpoints for content access authorization
  - name: Authorization (Optional)
    description: Optional endpoints for content access authorization
  - name: Optional Features
    description: Optional features that must be explicitly activated