publiq Permissions API

openapi: 3.2.0
info:
  title: Publiq Permissions API
  version: '4.0'
  contact:
    name: publiq helpdesk
    email: technical-support@publiq.be
    url: https://docs.publiq.be
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Permissions across 2 of this provider''s published API definitions: uitpas-uitpas.json, publiq-uitpas-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-test.uitpas.be
  description: Testing
- url: https://api.uitpas.be
  description: Production
tags:
- name: Permissions
paths:
  /permissions:
    parameters: []
    get:
      summary: Get permissions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizerPermissions'
              examples:
                Example with multiple organizers:
                  value:
                  - organizer:
                      id: c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1
                      name: CC De Werf
                      address:
                        postalCode: '9300'
                        city: Aalst
                      linkedLocationId: db18c985-c6a3-4454-9875-b28f74a9b823
                    permissions:
                    - TARIFFS_READ
                    - TICKETSALES_SEARCH
                    permissionDetails:
                    - id: TARIFFS_READ
                      label:
                        nl: Tarieven opvragen
                      cardSystemIds:
                      - 1
                    - id: TICKETSALES_SEARCH
                      label:
                        nl: Ticketsales zoeken
                      cardSystemIds:
                      - 1
                    linkedOrganizers:
                    - organizer:
                        id: 347e6177-4add-4fa8-a7fe-6e60127bfb12
                        name: Sportdienst
                        address:
                          postalCode: '9300'
                          city: Aalst
                        linkedLocationId: db18c985-c6a3-4454-9875-b28f74a9b823
                      permissionDetails:
                      - id: CHECKINS_WRITE
                        label:
                          nl: Punten sparen
                        cardSystemIds:
                        - 1
                  - organizer:
                      id: fd7e6177-4add-4fa8-a7fe-6e60127bfb35
                      name: CC De Schakel
                      address:
                        postalCode: '9300'
                        city: Aalst
                      linkedLocationId: fb18c985-c6a3-4454-9875-b28f74a9b809
                    permissions:
                    - ORGANIZERS_SEARCH
                    permissionDetails:
                    - id: ORGANIZERS_SEARCH
                      label:
                        nl: Organisators zoeken
                      cardSystemIds:
                      - 1
                Example with one organizer:
                  value:
                  - organizer:
                      id: c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1
                      name: CC De Werf
                      address:
                        postalCode: '9300'
                        city: Aalst
                      linkedLocationId: fb18c985-c6a3-4454-9875-b28f74a9b809
                    permissions:
                    - TARIFFS_READ
                    - TICKETSALES_SEARCH
                    permissionDetails:
                    - id: TARIFFS_READ
                      label:
                        nl: Tarieven opvragen
                      cardSystemIds:
                      - 1
                    - id: TICKETSALES_SEARCH
                      label:
                        nl: Ticketsales zoeken
                      cardSystemIds:
                      - 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: get-permissions
      description: 'Lists the organizers that the current user or client (depending on the token) has access to including a list of its permissions.


        The OrganizerPermission response object can also contain `linkedOrganizers` for which admins of this organizer also have access to.


        Use this endpoint if you obtained a user or client access token and need to know its organizer permissions. Use GET /permissions/clientID to manage permissions for any client.'
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      tags:
      - Permissions
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /permissions/{clientId}:
    parameters:
    - schema:
        type: string
      name: clientId
      in: path
      required: true
      description: ID of the client
    get:
      summary: Get permissions for a client
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizerPermissions'
              examples:
                Example:
                  value:
                  - organizer:
                      id: c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1
                      name: CC De Werf
                      address:
                        postalCode: '9300'
                        city: Aalst
                      linkedLocationId: fb18c985-c6a3-4454-9875-b28f74a9b809
                    permissionDetails:
                    - id: TARIFFS_READ
                      label:
                        nl: Tarieven opvragen
                      cardSystemIds:
                      - 1
                    - id: TICKETSALES_SEARCH
                      label:
                        nl: Ticketsales zoeken
                      cardSystemIds:
                      - 1
                  - organizer:
                      id: fd7e6177-4add-4fa8-a7fe-6e60127bfb35
                      name: CC De Schakel
                      address:
                        postalCode: '9300'
                        city: Aalst
                      linkedLocationId: fb18c985-c6a3-4454-9875-b28f74a9b809
                    permissionDetails:
                    - id: ORGANIZERS_SEARCH
                      label:
                        nl: Organisators zoeken
                      cardSystemIds:
                      - 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not found. Possible error types:


            * https://api.publiq.be/probs/uitpas/client-not-found


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-permissions-clientId
      description: 'Lists the organizer permissions of the given client ID.


        Use this endpoint to manage permissions for any client. Use GET /permissions to retrieve permissions for your token (current client or user).


        The caller of this request must have `PERMISSIONS_READ` permission.'
      security:
      - CLIENT_ACCESS_TOKEN: []
      tags:
      - Permissions
    put:
      summary: Update permissions for a client
      operationId: put-permissions-clientId
      responses:
        '204':
          description: Permissions Updated. No Content
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/body/missing

            * https://api.publiq.be/probs/body/invalid-syntax

            * https://api.publiq.be/probs/body/invalid-data'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not found. Possible error types:


            * https://api.publiq.be/probs/uitpas/client-not-found


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Update the organizer permissions of the given client ID.


        The caller of this request must have `PERMISSIONS_WRITE` permission.'
      security:
      - CLIENT_ACCESS_TOKEN: []
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/OrganizerPermissions'
            examples:
              Example:
                value:
                - organizer:
                    id: c097fa2e-d9be-42e6-b41a-ec3d4d4cbad1
                  permissionDetails:
                  - id: TARIFFS_READ
                  - id: TICKETSALES_SEARCH
                - organizer:
                    id: fd7e6177-4add-4fa8-a7fe-6e60127bfb35
                  permissionDetails:
                  - id: ORGANIZERS_SEARCH
        description: Full set of organizer permissions for the client
      tags:
      - Permissions
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
components:
  responses:
    Unauthorized:
      description: 'Unauthorized. Your request is missing the required credentials to authenticate. See the Authentication documentation for more info.


        * type: https://api.publiq.be/probs/auth/unauthorized

        * detail: might contain a developer-readable explanation of the reason'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          x-examples:
            Unauthorized:
              value:
                type: https://api.publiq.be/probs/auth/unauthorized
                title: Unauthorized
                status: 401
    Forbidden:
      description: 'Forbidden. Your request was successfully authenticated but you do not have permission to perform this particular request.


        * type: https://api.publiq.be/probs/auth/forbidden

        * detail: might contain a developer-readable explanation of the reason'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          x-examples:
            Forbidden:
              value:
                type: https://api.publiq.be/probs/auth/forbidden
                title: Forbidden
                status: 403
                detail: user must be admin of organiser abcd1234
  schemas:
    PermissionDetail:
      type: object
      title: PermissionDetail
      description: Permission details
      properties:
        id:
          $ref: '#/components/schemas/Permission'
        label:
          type: object
          description: Human-readable label of the permission
          properties:
            nl:
              type: string
              description: Human-readable label of the permission in Dutch
            en:
              type: string
              description: Human-readable label of the permission in English
          required:
          - nl
        cardSystemIds:
          type: array
          description: IDs of the card systems to which this permission applies
          items:
            type: integer
            readOnly: true
      required:
      - id
    Error:
      $ref: https://raw.githubusercontent.com/cultuurnet/apidocs/main/projects/errors/models/Error.json
    City:
      title: City
      type: object
      x-tags:
      - Models
      example:
        postalCode: '9300'
        name: Aalst
      properties:
        postalCode:
          type: string
          description: Postalcode of the city
        name:
          type: string
          description: Name of the city
      required:
      - postalCode
      - name
    Permission:
      title: Permission
      type: string
      x-tags:
      - Models
      enum:
      - TARIFFS_READ
      - TICKETSALES_SEARCH
      - TICKETSALES_REGISTER
      - EVENTS_UPDATE
      - EVENTS_READ
      - EVENT_SETTINGS_READ
      - EVENT_SETTINGS_UPDATE
      - EVENTS_UPDATE_ALL
      - EVENTS_READ_ALL
      - EVENT_SETTINGS_READ_ALL
      - EVENT_SETTINGS_UPDATE_ALL
      - EVENTS_QR_CHECKINCODE
      - CHECKINS_READ
      - CHECKINS_WRITE
      - ORGANIZERS_SEARCH
      - ORGANIZERS_REPORTS
      - ORGANIZERS_ADMINS_READ
      - ORGANIZERS_ADMINS_WRITE
      - PASSHOLDERS_PICTURE_READ
      - PASSHOLDERS_PICTURE_WRITE
      - PASSHOLDERS_PRIVATE_READ
      - PASSHOLDERS_PRIVATE_WRITE
      - PASSHOLDERS_SEARCH
      - PASSHOLDERS_SEARCH_ALL
      - PASSHOLDERS_SEARCH_BY_ID
      - GROUPPASSES_SEARCH
      - PASSHOLDERS_WRITE
      - PASSHOLDERS_WRITE_SOCIALTARIFF_FULL_CARDSYSTEM
      - PASSHOLDERS_WRITE_FOREIGN_COUNTRY
      - PASSHOLDERS_WRITE_SOCIALTARIFF
      - PASSHOLDERS_UPDATE
      - PASSHOLDERS_DELETE
      - PASSHOLDER_COUPONS_READ
      - GROUPPASS_COUPONS_READ
      - MEMBERSHIP_PRICES_READ
      - PASSES_READ
      - PASSES_INSZNUMBERS_READ
      - PASSES_CHIPNUMBERS_READ
      - REWARDS_WRITE
      - REWARDS_READ
      - REWARDS_REDEEM
      - REWARDS_PASSHOLDERS_READ
      - PASSHOLDERS_SELF_REGISTRATION
      - PASSHOLDERS_SELF_CHECKIN
      - PASSHOLDERS_SELF_READ
      - PASSHOLDERS_REGISTER_UITID
      - PASSHOLDERS_TRANSACTION_HISTORY
      - PASSHOLDERS_FAMILY_MEMBERS
      - ORDERS_READ
      - ORDERS_CREATE
      - PERMISSIONS_READ
      - PERMISSIONS_WRITE
      - CARDS_READ
      - ASSOCIATIONS
      - SOCIALTARIFF_EXPORT
      - KIOSKS_READ
      - KIOSKS_WRITE
      description: ID of the permission
    OrganizerPermissions:
      title: OrganizerPermissions
      type: object
      x-tags:
      - Models
      description: Combination of organizer and its permissions
      properties:
        organizer:
          $ref: '#/components/schemas/Organizer'
        permissions:
          type: array
          description: Permissions of the calling client for this organizer. This field is deprecated. Please use `permissionDetails`, which includes a user-readable label, instead.
          deprecated: true
          items:
            $ref: '#/components/schemas/Permission'
        permissionDetails:
          description: Permissions of the calling client for this organizer.
          type: array
          items:
            $ref: '#/components/schemas/PermissionDetail'
        linkedOrganizers:
          type: array
          description: Organizers linked to this organizer.
          items:
            $ref: '#/components/schemas/LinkedOrganizerPermissions'
      required:
      - organizer
    Organizer:
      title: Organizer
      type: object
      description: An organisation that partners with UiTPAS to provide discounts and/or rewards, and/or allows points to be collected at their events.
      x-tags:
      - Models
      properties:
        id:
          type: string
          description: Unique ID of an UiTPAS organizer. (Same as its ID in UiTdatabank)
        name:
          type: string
          description: Human-readable name of an UiTPAS organizer.
        cardSystems:
          type: array
          description: Card systems linked to this organizer
          items:
            $ref: '#/components/schemas/CardSystem'
        linkedLocationId:
          type: string
          description: ID of the location linked to this organizer.
          readOnly: true
        address:
          type: object
          description: Address of this organizer. This property is alway available in responses.
          required:
          - city
          properties:
            street:
              type: string
              description: Street address of this organizer
            postalCode:
              type: string
              description: Postal code of this organizer
            city:
              type: string
              description: City of this organizer
          readOnly: true
      required:
      - id
    CardSystem:
      title: CardSystem
      description: A region, usually one or multiple municipalities in Belgium, that uses UiTPAS and provides discounts and/or rewards. For example "Paspartoe" (Brussels), UiTPAS Leuven, UiTPAS Hasselt, UiTPAS Gent, and so on.
      type: object
      x-tags:
      - Models
      example:
        id: 1
        name: UiTPAS Dender
        branding:
          logo: https://www.uitpas.be/_nuxt/img/1351557.svg
          primaryColor: rgba(0,0,0,1.0)
          secondaryColor: rgba(97,166,14,1.0)
        links:
          website: https://www.uitpas.be
        cities:
        - postalCode: '9300'
          name: Aalst
        - postalCode: '9400'
          name: Ninove
        permanent: true
      properties:
        id:
          type: integer
          description: ID of the card system
        name:
          type: string
          description: Name of the card system. This field is always available in responses.
        branding:
          type: object
          description: Branding information of the card system
          properties:
            logo:
              type: string
              description: URL to the logo of the card system
            primaryColor:
              type: string
              description: Color code of the primary branding color.
            secondaryColor:
              type: string
              description: Color code of the secondary branding color.
        links:
          type: object
          description: Links of the card system
          properties:
            website:
              type: string
              description: URL of the website of the card system
        cities:
          type: array
          description: List of cities that are part of this card system
          items:
            $ref: '#/components/schemas/City'
        permanent:
          type: boolean
          description: Indicates whether this is a permanent card system
        allowsCardlessRegistration:
          type: boolean
          description: Indicates if cardless registration is enabled
        cardlessRegistrationType:
          type: string
          description: Indicates the types of online cardless registrations this cardsystem supports.
          enum:
          - ALL
          - REGULAR
          - SOCIALTARIFF
          - NONE
        socialTariffInfo:
          type: string
          description: Optional information about social tariff entitlement in this card system.
      required:
      - id
    LinkedOrganizerPermissions:
      title: LinkedOrganizerPermissions
      type: object
      x-tags:
      - Models
      properties:
        organizer:
          $ref: '#/components/schemas/Organizer'
        permissionDetails:
          description: Permissions of the calling client for this organizer.
          type: array
          items:
            $ref: '#/components/schemas/PermissionDetail'
      required:
      - organizer
      description: Combination of organizer and its permissions, specifically targetted to be used when linked to another organizer.
    Error_2:
      title: Error
      type: object
      description: RFC7807 error model for all publiq APIs.
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. Can be used to recognize specific errors in your application code by comparing the complete URI.
        title:
          type: string
          description: A short, human-readable summary of the problem type (for developers).
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: 'A human-readable explanation specific to this occurrence of the problem (for developers). '
        endUserMessage:
          type: object
          description: A human-readable explanation of the problem, specifically for end-users, in one or more languages. Typically available for domain errors, but not for errors caused by a technical issue in the integration (for example invalid JSON syntax in a request body). An `nl` value is always provided, other languages may be provided depending on the API and its intended audience. When this property is included, it is strongly encouraged to show this to the end-user.
          properties:
            nl:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in Dutch.
            fr:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in French.
            de:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in German.
            en:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in English.
          required:
          - nl
        schemaErrors:
          type: array
          description: A list of one or more schema validation errors (usually used for error type https://api.publiq.be/probs/body/invalid-data).
          items:
            type: object
            properties:
              jsonPointer:
                type: string
                format: json-pointer
                description: RFC6901 compliant pointer that indicates what property/value was invalid.
              error:
                type: string
                description: A human-readable (but often technical) reason why the property was invalid.
            required:
            - jsonPointer
            - error
      required:
      - type
      - title
      - status
      x-internal: false
  securitySchemes:
    USER_ACCESS_TOKEN:
      type: oauth2
      flows: {}
      description: A user access token, obtained by redirecting the end user to publiq's authorization server to login using the **Authorization Code OAuth Flow**. See the [authentication docs about user access tokens](https://docs.publiq.be/docs/authentication/methods/user-access-token) for more info.
    CLIENT_ACCESS_TOKEN:
      type: oauth2
      flows: {}
      description: A client access token, obtained by exchanging your client id and client secret for a token via an HTTP request to publiq's authorization server using the **Client Credentials OAuth Flow**. See the [authentication docs about client access tokens](https://docs.publiq.be/docs/authentication/methods/client-access-token) for more info.
    CLIENT_IDENTIFICATION:
      name: x-client-id
      type: apiKey
      in: header
    CUSTOM_TOKEN:
      name: x-custom-token
      type: apiKey
      in: header
x-refined-from:
- uitpas-uitpas.json
- publiq-uitpas-openapi.yml