openapi: 3.0.3
info:
  title: Open-Gateway API V1
  description: >-
    This API provides methods to obtain the capabilities of CAMARA project in
    mas-stack.


    The functionality it will currently have will be for AuthN and its purpose
    will be, given an MSISDN, scope, purpose and application, to return whether
    the MSISDN gives consent for the capability query to be performed for the
    indicated application.


    Service Enabling Network Function API to verify that the provided **mobile
    phone number** is the one used in the device. It verifies that the user is
    using a device with the same *mobile phone number* as it is declared.

    It also makes it possible for a Service provider to verify the number itself
    by returning the phone number associated to the authenticated user's access
    token.


    In this API **phone number** term refers to the mobile phone number.


    # Introduction


    Number Verification API performs real-time checks to verify the phone number
    of the mobile device being used to access a service provider (SP) service,
    where the mobile device is accessing the *service provider* over a mobile
    network (WiFi connections are out of this API scope) either by getting the
    comparison result or receiving the phone number of the device that it is
    used, so they can verify it themselves.


    It uses direct mobile network connections to verify possession of a phone
    number in the background without requiring user interaction. There are
    neither OTPs (One-time passwords) received by SMS nor authenticator app
    downloads, so it is much simpler. It can be used at sign up, login, or
    transaction time to validate that a user's SIM (Subscriber Identity Module)
    is both actively connected to the mobile network and not spoofed or cloned.



    # Relevant Definitions and Concepts


    - **Network-Based Authentication**: Authentication mechanism based on the
    identification of the endpoint of a network connection. Network operators
    know to which subscriber a network resource is assigned at a given moment,
    for example the mobile phone number associated to a specific mobile network
    connection.


    # API Functionality


    This enables a Service Provider (SP) to verify the phone number of the
    mobile device being used to access their service where the mobile device is
    accessing the *service provider* over a mobile network (WiFi connections are
    out of this API scope). This can happen either by getting the comparison
    result or receiving the phone number of the device that is used, so they can
    verify it themselves.


    # Resources and Operations overview

    This API currently provides two endpoints where both require a **3-legged
    token** and authentication via **mobile network** (**excluding** for example
    by SMS/OTP or user/password as an authentication method):

    - The first one checks if the user mobile phone number matches the phone
    number associated with the mobile device. It can receive either a hashed or
    a plain text phone number as input and it compares the received input with
    the authenticated user's phone number associated to the access token in
    order to respond **true/false**.


    # Sequence Diagram

    Number Verification API uses the **standard [OIDC Authorization Code
    Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)**.
    The following diagram will help to clarify the end-to-end process, including
    previous steps prior to this API call.


    Note that the diagram shows just an example of a direct integration from
    developer's application and MNO's authserver and API, other scenarios of
    indirect integration via Aggregator/Channel Partner should also be
    considered. Specific authorization flows may apply, as defined by e.g. GSMA
    Open Gateway (OGW).


    ![UML Sequence
    Diagram](https://raw.githubusercontent.com/camaraproject/NumberVerification/main/documentation/API_documentation/assets/uml_v0.3.jpg)


    # Authorization and authentication


    The "Camara Security and Interoperability Profile" provides details on how a
    client requests an access token. Please refer to Identify and Consent
    Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
    for the released version of the Profile.


    Which specific authorization flows are to be used will be determined during
    onboarding process, happening between the API Client and the Telco Operator
    exposing the API, taking into account the declared purpose for accessing the
    API, while also being subject to the prevailing legal framework dictated by
    local legislation.


    It is important to remark that in cases where personal user data is
    processed by the API, and users can exercise their rights through mechanisms
    such as opt-in and/or opt-out, the use of 3-legged access tokens becomes
    mandatory. This measure ensures that the API remains in strict compliance
    with user privacy preferences and regulatory obligations, upholding the
    principles of transparency and user-centric data control.


    In the case of the Number Verification API scenario and according to the API
    definition, 3-legged access tokens must be used by API clients to invoke
    this API with dedicated scope. The API client must authenticate on behalf of
    a specific user to use this service. This must be done via mobile network
    authentication.


    # Further info and support

    [GSMA Mobile Connect Verified MSISDN
    specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf)
    was used as source of input for this API.  For more about Mobile Connect,
    please see [Mobile Connect website](https://mobileconnect.io/).


    The SIM swap API provides a programmable interface for developers and other
    users (capabilities consumers) to request the last date of a SIM swap
    performed on the mobile line, or, to check whether a SIM swap has been
    performed during a past period.


    # Introduction


    The SIM Swap API performs real-time checks on the last SIM Swap event.


    The SIM Swap API is useful to prevent fraud by reducing the risk of account
    takeover fraud by strengthening SIM based authentication processes such as
    SMS One-time passwords. Fraudsters are using SIM swap techniques to
    intercept SMS messages and reset passwords or receive verification codes
    that allow them to access protected accounts.


    The SIM Swap API can also be used to protect non-automated actions. For
    example, when a call center expert contacts a user to clarify or confirm a
    sensitive operation.


    This API is used by an application to get information about a mobile line
    latest SIM swap date. It can be easily integrated and used through this
    secured API and allows SPs (Service Provider) to get this information an
    easy & secured way. The API provides management of 2 endpoints answering 2
    distinct questions:


    * When did the last SIM swap occur?

    * Has a SIM swap occurred during last n hours?


    # Relevant terms and definitions


    **SIM swap**:

    A SIM swap is a process in which a user's mobile phone number (MSISDN) is
    associated with a new SIM card (IMSI). This is typically done by contacting
    the user's mobile service provider and requesting a new SIM card for various
    reasons, such as a lost or damaged SIM card or upgrading to a new phone.


    SIM swap also happens during other actions like changing user's phone
    number, changing mobile service provider keeping user's mobile phone number
    or when activating a new SIM associated to the same phone number, known as
    multisim service. New subscription is considered as a SIM swap as well, the
    MSISDN which can be used by another person earlier, is associated with a SIM
    card it was not associated before.


    # API functionality


    The API provides 2 operations:


    - POST retrieve-date : Provides timestamp of latest SIM swap, if any, for a
    given phone number. If no swap has been performed, the API will return the
    SIM activation date (the timestamp of the first time that the sim connected
    to the network) by default, unless this is not possible due to local
    regulations preventing the safekeeping of the information for longer than
    the stated period of time. If this is the case, a `null` value will be
    returned.


    - POST check: Checks if SIM swap has been performed during a past period
    (defined in the request with 'maxAge' attribute) for a given phone number.


    # Authorization and authentication


    The "Camara Security and Interoperability Profile" provides details on how a
    client requests an access token. Please refer to Identify and Consent
    Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
    for the released version of the Profile.


    Which specific authorization flows are to be used will be determined during
    onboarding process, happening between the API Client and the Telco Operator
    exposing the API, taking into account the declared purpose for accessing the
    API, while also being subject to the prevailing legal framework dictated by
    local legislation.


    It is important to remark that in cases where personal user data is
    processed by the API, and users can exercise their rights through mechanisms
    such as opt-in and/or opt-out, the use of 3-legged access tokens becomes
    mandatory. This measure ensures that the API remains in strict compliance
    with user privacy preferences and regulatory obligations, upholding the
    principles of transparency and user-centric data control.


    # Identifying a phone number from the access token


    This specification defines the `phoneNumber` field as optional in API
    requests, specifically in cases where the API is accessed using a 3-legged
    access token, and the phone number can be uniquely identified by the token.
    This approach simplifies API usage for API consumers by relying on the
    information associated with the access token used to invoke the API.


    ## Handling of phone number information:


    ### Optional `phoneNumber` field for 3-legged tokens:


    - When using a 3-legged access token, the phone number associated with the
    access token must be considered as the phone number for the API request.
    This means that the `phoneNumber` field is not required in the request, and
    if included it must identify the same phone number, therefore **it is
    recommended NOT to include it in these scenarios** to simplify the API usage
    and avoid additional validations.


    ### Validation mechanism:


    - The server will extract the phone number identification from the access
    token, if available.

    - If the API request additionally includes a `phoneNumber` field when using
    a 3-legged access token, the API will validate that the phone number
    provided matches the one associated with the access token.

    - If there is a mismatch, the API will respond with a 403 -
    INVALID_TOKEN_CONTEXT error, indicating that the phone number information in
    the request does not match the token.


    ### Error handling for unidentifiable phone number:


    - If the `phoneNumber` field is not included in the request and the phone
    number information cannot be derived from the 3-legged access token, the
    server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error.


    ### Restrictions for tokens without an associated authenticated phone
    number:


    - For scenarios which do not have a phone number associated to the token
    during the authentication flow, e.g. 2-legged access tokens, the
    `phoneNumber` field MUST be provided in the API request. This ensures that
    the phone number is explicit and valid for each API call made with these
    tokens.


    # Further info and support


    [GSMA Mobile Connect Account Takeover Protection
    specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.24-Mobile-Connect-Account-Takeover-Protection-Definition-and-Technical-Requirements-v2.0.pdf)
    was used as source of input for this API. For more about Mobile Connect,
    please see [Mobile Connect website](https://mobileconnect.io/).


    (FAQs will be added in a later version of the documentation)


    To consume Open Gateway capabilities, an authorization flow is required
    through which clients obtain a token with the necessary permissions/scopes 

    to access the requested information.


    API for managing View OpenGateway and Capabilities catalog.

    This service provides CRUD operations for capability management.


    Internal API exposing the catalog of tenants provisioned in the Open Gateway
    domain,

    optionally scoped by backend stack.


    API for managing Product Orders and their per-tenant status.

    This service provides CRUD operations for product order management.


    The Quality-of-Service (QoS) Profiles API provides a set of predefined
    network performance characteristics, such as latency, throughput, and
    priority, identified by a unique name. These profiles allow application
    developers to specify the desired network behavior for their application's
    data traffic, ensuring optimal performance. By selecting an appropriate QoS
    profile, developers can request stable latency (reduced jitter) or
    throughput for specific data flows between client devices and application
    servers when used by the Quality-On-Demand APIs.


    # Introduction


    QoS Profiles are used in conjunction with other Quality-On-Demand APIs, to
    offer the API consumer the capability to request for stable latency (reduced
    jitter) or throughput for some specified application data flows between
    application clients (within a user device) and Application Servers (backend
    services). The API consumer has a pre-defined set of Quality of Service
    (QoS) profiles which they could choose from depending on their latency or
    throughput requirements. The QoS profiles are defined by the API provider
    and are mapped to the connectivity characteristics of the supported
    networks.


    # API functionality


    The QoS Profiles API provides the following functionality:

    - Discover all QoS profiles offered by the API provider

    - Discover the available QoS profiles for a specific device

    - Retrieve the characteristics of a specific QoS profile by name


    How QoS profiles are mapped to connectivity characteristics are subject to
    agreements between the API provider and the API consumer. Within the CAMARA
    project, you can find a sample for such a mapping of QoS profiles. [CAMARA
    QoS Profiles Mapping Table (REFERENCE
    DRAFT)](https://github.com/camaraproject/QualityOnDemand/blob/r3.2/documentation/API_documentation/QoSProfile_Mapping_Table.md)


    # Authorization and authentication


    The "Camara Security and Interoperability Profile" provides details of how
    an API consumer requests an access token. Please refer to Identity and
    Consent Management
    (https://github.com/camaraproject/IdentityAndConsentManagement/) for the
    released version of the profile.


    The specific authorization flows to be used will be agreed upon during the
    onboarding process, happening between the API consumer and the API provider,
    taking into account the declared purpose for accessing the API, whilst also
    being subject to the prevailing legal framework dictated by local
    legislation.


    In cases where personal data is processed by the API and users can exercise
    their rights through mechanisms such as opt-in and/or opt-out, the use of
    three-legged access tokens is mandatory. This ensures that the API remains
    in compliance with privacy regulations, upholding the principles of
    transparency and user-centric privacy-by-design.


    # Identifying the device from the access token


    The two operations defined by this API (`getQosProfile` and
    `retrieveQoSProfiles`) both allow the API consumer to use a three-legged
    access token to specify a target device as a query filter. When provided,
    only profiles available to the specified target device will be returned.
    Additionally, when a two-legged access token is used, the operation
    `retrieveQoSProfiles` allows the API consumer to optionally specify the
    target device in the request body.


    Hence, for the `retrieveQoSProfiles` operation:

    - When invoked using a two-legged access token, the optional input device
    object will be used as filter if present.


    - When invoked using a three-legged access token, this optional identifier
    in the request body MUST NOT be provided, as the device to filter will be
    uniquely identified from the access token.


    This approach simplifies API usage for API consumers using a three-legged
    access token to invoke the API by relying on the information that is
    associated with the access token and was identified during the
    authentication process.


    ## Error handling:

    - If the device can be identified from the access token and the optional
    `device` object is also included in the request, then the server will return
    an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the
    case even if the same device is identified by these two methods, as the
    server is unable to make this comparison.


    # Multi-SIM scenario handling


    In multi-SIM scenarios where more than one mobile device is associated with
    a phone number (e.g. a smartphone with an associated smartwatch), it might
    not be possible to uniquely identify a single device from that phone number.
    When filtering QoS profiles by device in such scenarios, one of the
    following options should be used:

    - Use the authorisation code flow to obtain a 3-legged access token, which
    will automatically identify the intended device

    - Identify the intended device from a unique identifier for that device,
    such as its source IP address and port

    - Check with the SIM provider whether a unique "secondary" phone number is
    already associated with each device, and use the secondary phone number to
    identify the intended device if available


    # Additional CAMARA error responses


    The list of error codes in this API specification is not exhaustive.
    Therefore the API specification may not document some non-mandatory error
    statuses as indicated in `CAMARA API Design Guide`.


    Please refer to the `CAMARA_common.yaml` of the Commonalities Release
    associated to this API version for a complete list of error responses. The
    applicable Commonalities Release can be identified in the `API Readiness
    Checklist` document associated to this API version.


    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible
    error response if it is explicitly documented in the API.


    The Quality-On-Demand (QoD) API provides a programmable interface for
    developers and other users (API consumers) to request stable latency or
    throughput managed by networks without the necessity to have an in-depth
    knowledge of the underlying network complexity (e.g. the 4G/5G system in
    case of a mobile network).


    # Introduction


    Industrial (IoT), VR/Gaming, live video streaming, autonomous driving and
    many other scenarios demand network communication quality and are sensitive
    to any change in transmission conditions. Being able to request a stable
    latency (reduced jitter) or prioritized throughput from the network can
    improve user experience substantially.


    The QoD API offers the application developers the capability to request for
    stable latency (reduced jitter) or throughput for some specified application
    data flows between application clients (within a user device) and
    application servers (backend services). The developer has a pre-defined set
    of Quality of Service (QoS) profiles which they could choose from depending
    on their latency or throughput requirements.


    ![QoD API
    Overview](https://raw.githubusercontent.com/camaraproject/QualityOnDemand/r3.2/documentation/API_documentation/resources/QoD_latency_overview.PNG)


    The usage of the API is based on QoS session resources, which can be created
    (based on available QoS profiles), queried and deleted. The deletion of a
    requested session can be triggered by the API consumer or can be triggered
    automatically once the QoS session has reached its limit.


    # Relevant terms and definitions


    * **QOD service endpoint**:

    The URL pointing to the RESTful resource of the QoD API.


    * **Authentication**:

    Security access keys such as OAuth 2.0 client credentials used by client
    applications to invoke the QoD API.


    * **QoS profiles**:

    Latency, throughput or priority requirements of the application mapped to
    relevant QoS profile values. The set of QoS Profiles that an API provider is
    offering may be retrieved via the `qos-profiles` API (cf.
    https://github.com/camaraproject/QualityOnDemand/) or will be agreed during
    the onboarding with the API provider.


    * **Identifier for the device**:

    At least one identifier for the device (user equipment) out of four options:
    IPv4 address, IPv6 address, Phone Number, or Network Access Identifier
    assigned by the mobile network operator for the device. Where more than one
    device identifier is provided, only one identifier will be selected by the
    implementation and this choice indicated to the API consumer in the session
    details. If only a single device identifier is provided, the implementation
    may or may not include the device identifier in the session details.

      Note: Network Access Identifier is defined for future use and will not be supported with this version of the API.

    * **Identifier for the application server**:

    IPv4 and/or IPv6 address of the application server (application backend)


    * **App-Flow (between the application client and application server)**:

    The precise application data flow the developer wants to prioritize and have
    stable latency or throughput for. This flow is in the current API version
    determined by the identified device and the application server. And it can
    be further elaborated with details such as ports or port-ranges. Future
    version of the API might allow more detailed flow identification features.


    * **Duration**:

    Duration (in seconds) for which the QoS session (between application client
    and application server) should be created. Limits for session duration can
    be set by the implementation for the QoS profile. The user may request a
    termination before its expiration.

     * **Notification URL and token**:
    The API consumer may provide a callback URL (`sink`) on which notifications
    about all status change events (eg. session termination) can be received
    from the API provider. This is an optional parameter. The notification will
    be sent as a CloudEvent compliant message.

    If `sink` is included, it is RECOMMENDED for the client to provide as well
    the `sinkCredential` property to protect the notification endpoint. In the
    current version, `sinkCredential.credentialType` MUST be set to
    `ACCESSTOKEN` if provided.


    # API functionality


    The usage of the QoD API is based on QoS profile classes and parameters
    which define App-Flows.

    Based on the API, QoS session resources can be created, queried, and
    deleted. Once an offered QoS profile class is requested, application users
    get a prioritized service with stable latency or throughput even in the case
    of congestion. The QoD API has the following characteristics:


    * A specified App-Flow is prioritized to ensure stable latency or throughput
    for that flow.

    * The prioritized App-Flow is described by providing information such as
    device IP address (or other device identifier) & application server IP
    addresses and port/port-ranges.

    * The developer specifies the duration for which they need the prioritized
    App-flow.

    * Stable latency or throughput is requested by selecting from the list of
    QoS profiles made available by the service provider (e.g. QOS_E) to map
    latency and throughput requirements.

    * The API consumer can optionally also specify callback URL (`sink` param)
    on which notifications for the session can be sent. <br>


    Following diagram shows the interaction between different components


    ![QoD Management
    API](https://raw.githubusercontent.com/camaraproject/QualityOnDemand/r3.2/documentation/API_documentation/resources/QoD_details.PNG)


    # Authorization and authentication


    The "Camara Security and Interoperability Profile" provides details of how
    an API consumer requests an access token. Please refer to Identity and
    Consent Management
    (https://github.com/camaraproject/IdentityAndConsentManagement/) for the
    released version of the profile.


    The specific authorization flows to be used will be agreed upon during the
    onboarding process, happening between the API consumer and the API provider,
    taking into account the declared purpose for accessing the API, whilst also
    being subject to the prevailing legal framework dictated by local
    legislation.


    In cases where personal data is processed by the API and users can exercise
    their rights through mechanisms such as opt-in and/or opt-out, the use of
    three-legged access tokens is mandatory. This ensures that the API remains
    in compliance with privacy regulations, upholding the principles of
    transparency and user-centric privacy-by-design.


    # Identifying the device from the access token


    This API requires the API consumer to identify a device as the subject of
    the API as follows:

    - When the API is invoked using a two-legged access token, the subject will
    be identified from the optional `device` object, which therefore MUST be
    provided.


    - When a three-legged access token is used however, this optional identifier
    MUST NOT be provided, as the subject will be uniquely identified from the
    access token.


    This approach simplifies API usage for API consumers using a three-legged
    access token to invoke the API by relying on the information that is
    associated with the access token and was identified during the
    authentication process.


    ## Error handling:

    - If the subject cannot be identified from the access token and the optional
    `device` object is not included in the request, then the server will return
    an error with the `422 MISSING_IDENTIFIER` error code.


    - If the subject can be identified from the access token and the optional
    `device` object is also included in the request, then the server will return
    an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the
    case even if the same device is identified by these two methods, as the
    server is unable to make this comparison.


    - If the requested `qosProfile` exists but is currently not available for
    creating a session (e.g., its status is INACTIVE or DEPRECATED), then the
    server will return an error with the `422
    QUALITY_ON_DEMAND.QOS_PROFILE_NOT_APPLICABLE` error code.


    # Multi-SIM scenario handling


    In multi-SIM scenarios where more than one mobile device is associated with
    a phone number (e.g. a smartphone with an associated smartwatch), it might
    not be possible to uniquely identify the device to which the enhanced QoS
    profile should apply from that phone number. If the phone number is used as
    the device identifier when creating a QoS session in a multi-SIM scenario,
    the API may respond with an error, apply the enhanced QoS profile to all
    devices in the multi-SIM group, or apply the enhanced QoS profile to a
    single device in the multi-SIM group which may not be the intended device.


    Possible solutions in such a scenario include:

    - Using the authorisation code flow to obtain an access token, which will
    automatically identify the intended device

    - Identifying the intended device from a unique identifier for that device,
    such as its source IP address and port

    - Check with the SIM provider whether a unique "secondary" phone number is
    already associated with each device, and use the secondary phone number to
    identify the intended device if available


    # Additional CAMARA error responses


    The list of error codes in this API specification is not exhaustive.
    Therefore the API specification may not document some non-mandatory error
    statuses as indicated in `CAMARA API Design Guide`.


    Please refer to the `CAMARA_common.yaml` of the Commonalities Release
    associated to this API version for a complete list of error responses. The
    applicable Commonalities Release can be identified in the `API Readiness
    Checklist` document associated to this API version.


    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible
    error response if it is explicitly documented in the API.
  version: 0.25.0
servers:
  - url: 'https://opengateway.masstack.com/v1/'
    description: production
  - url: 'https://opengateway.sta.masstack.com/v1/'
    description: staging
tags:
  - name: Consents
    description: API operation of consents.
  - name: Number Verification
    description: API operation of Number Verification API.
  - name: Sim Swap
    description: API operation of Sim Swap API.
  - name: Create application
    description: >-
      API operation to create an application and a client in AuthN after Orange
      performs a POST request to ApplicationOwner.
  - name: Capabilities
    description: Operations for managing CAMARA capabilities
  - name: Views
    description: Operations for managing View OpenGateway consent views
  - name: TenantCatalog
    description: Operations for the Open Gateway tenant catalog
  - name: Product Orders
    description: Operations for managing Product Orders
  - name: Product Order Status
    description: Operations for managing per-tenant Product Order status
  - name: QoSProfiles
    description: Manage QoS Profiles
  - name: QoD
    description: Manage QoD sessions
paths:
  '/orgs/{org_id}/consents/validate':
    post:
      tags:
        - Consents
      summary: >-
        Given an MSISDN, scope, purpose, and application, return whether the
        MSISDN consents to the capability query for the given application.
      description: >-
        Given an MSISDN, scope, purpose, and application, return whether the
        MSISDN consents to the capability query for the given application.
      operationId: validateConsents
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentsValidateRequest'
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  purpose:
                    type: string
                    description: >-
                      Purpose for which the capability is to be consumed.
                      Typically this will start with 'dpv:' followed by a value
                      from the Data Privacy Vocabulary (DPV) ontology.
                    example: 'dpv:FraudPreventionAndDetection'
                  consents:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsentsValidateResponse'
                example:
                  purpose: 'dpv:FraudPreventionAndDetection'
                  consents:
                    - id: SimSwap_FraudPreventionAndDetection_Agregador1App1
                      scope: sim-swap
                      status: ACCEPTED
                      expiration_date: '2025-12-31T23:59:59'
                    - id: >-
                        NumberVerification_FraudPreventionAndDetection_Agregador2App2
                      scope: 'number-verification:verify'
                      status: EXPIRED
                      expiration_date: '2024-01-01T00:00'
                    - id: KycMatch_FraudPreventionAndDetection_Agregador1App1
                      scope: kyc-match
                      status: PENDING
        '400':
          $ref: '#/components/responses/ConsentsGeneric400'
        '401':
          $ref: '#/components/responses/ConsentsGeneric401'
        '403':
          $ref: '#/components/responses/ConsentsGeneric403'
        '500':
          $ref: '#/components/responses/ConsentsGeneric500'
        '503':
          $ref: '#/components/responses/ConsentsGeneric503'
        '504':
          $ref: '#/components/responses/ConsentsGeneric504'
  '/orgs/{org_id}/consents/msisdn/{msisdn}':
    delete:
      tags:
        - Consents
      summary: Revoke all consents for a given MSISDN.
      description: >-
        Revokes all consents associated with the given MSISDN within the
        specified organization.
      operationId: revokeConsentByMsisdn
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: msisdn
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9]{9,14}$'
            example: '654388973'
      responses:
        '204':
          description: No Content. Consents revoked successfully.
        '400':
          $ref: '#/components/responses/ConsentsGeneric400'
        '401':
          $ref: '#/components/responses/ConsentsGeneric401'
        '403':
          $ref: '#/components/responses/ConsentsGeneric403'
        '500':
          $ref: '#/components/responses/ConsentsGeneric500'
        '503':
          $ref: '#/components/responses/ConsentsGeneric503'
        '504':
          $ref: '#/components/responses/ConsentsGeneric504'
  '/orgs/{org_id}/consents/create':
    post:
      tags:
        - Consents
      summary: >-
        Given an scope, purpose, and application (AppName and ClientName), check
        if the parent exists, and if exist, create a new consent.
      description: >
        Given an scope, purpose, and application (AppName and ClientName), check
        if the parent exists, and if exist, create a new consent.
      operationId: createConsent
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentsCreateRequest'
        required: true
      responses:
        '201':
          description: CREATED
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
        '400':
          $ref: '#/components/responses/ConsentsGeneric400'
        '401':
          $ref: '#/components/responses/ConsentsGeneric401'
        '403':
          $ref: '#/components/responses/ConsentsGeneric403'
        '500':
          $ref: '#/components/responses/ConsentsGeneric500'
        '503':
          $ref: '#/components/responses/ConsentsGeneric503'
        '504':
          $ref: '#/components/responses/ConsentsGeneric504'
  '/orgs/{org_id}/number-verification/verify':
    post:
      tags:
        - Number Verification
      summary: >-
        Verifies if the received hashed/plain text phone number matches the
        phone number associated with the access token
      description: >-
        Verifies if the specified phone number (either in plain text or hashed
        format) matches the one that the user is currently using. Only one of
        the plain or hashed formats must be provided. - The number verification
        will be done for the user that has authenticated via mobile network - It
        returns true/false depending on if the hashed phone number received as
        input matches the authenticated user's `device phone number` associated
        to the access token
      operationId: phoneNumberVerify
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationVerifyRequest'
            examples:
              PlainExample:
                summary: Plain MSISDN
                value:
                  referenceMsisdn: '+34611223344'
                  evidence:
                    type: PLAIN
                    value: '+34611223344'
              HashedExample:
                summary: HASHED_SHA256 MSISDN
                value:
                  referenceMsisdn: '+34611223344'
                  evidence:
                    type: HASHED_SHA256
                    value: >-
                      32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationMatchResponse'
        '400':
          $ref: '#/components/responses/NumberVerificationGeneric400'
        '401':
          $ref: '#/components/responses/NumberVerificationGeneric401'
        '403':
          $ref: '#/components/responses/NumberVerificationGeneric403'
        '500':
          $ref: '#/components/responses/NumberVerificationGeneric500'
        '503':
          $ref: '#/components/responses/NumberVerificationGeneric503'
        '504':
          $ref: '#/components/responses/NumberVerificationGeneric504'
  '/orgs/{org_id}/number-verification/device-phone-number':
    get:
      tags:
        - Number Verification
      summary: Returns the phone number associated with the access token
      description: >
        Returns the phone number so the API clients can verify the number
        themselves:

        - It will be done for the user that has authenticated via mobile network

        - It returns the authenticated user's `device phone number` associated
        to the access token
      operationId: phoneNumberShare
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: devicePhoneNumber
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/NumberVerificationDevicePhoneNumber'
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/NumberVerificationNumberVerificationShareResponse
        '400':
          $ref: '#/components/responses/NumberVerificationGeneric400'
        '401':
          $ref: '#/components/responses/NumberVerificationGeneric401'
        '403':
          $ref: '#/components/responses/NumberVerificationGeneric403'
        '500':
          $ref: '#/components/responses/NumberVerificationGeneric500'
        '503':
          $ref: '#/components/responses/NumberVerificationGeneric503'
        '504':
          $ref: '#/components/responses/NumberVerificationGeneric504'
  '/orgs/{org_id}/sim-swap/retrieve-date':
    post:
      tags:
        - Sim Swap
      description: >-
        Get timestamp of last SIM swap event for a mobile user account provided
        with phone number.
      operationId: retrieveSimSwapDate
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        description: |
          Create a SIM swap date request for a phone number.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimSwapCreateSimSwapDate'
        required: true
      responses:
        '200':
          description: Contains information about SIM swap change
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimSwapSimSwapInfo'
        '400':
          $ref: '#/components/responses/SimSwapGeneric400'
        '401':
          $ref: '#/components/responses/SimSwapGeneric401'
        '403':
          $ref: '#/components/responses/SimSwapGeneric403'
        '404':
          $ref: '#/components/responses/SimSwapGeneric404'
        '422':
          $ref: '#/components/responses/SimSwapGeneric422'
        '500':
          $ref: '#/components/responses/SimSwapGeneric500'
        '503':
          $ref: '#/components/responses/SimSwapGeneric503'
        '504':
          $ref: '#/components/responses/SimSwapGeneric504'
  '/orgs/{org_id}/sim-swap/check':
    post:
      tags:
        - Sim Swap
      description: Check if SIM swap has been performed during a past period
      operationId: checkSimSwap
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        description: |
          Create a check SIM swap request for a phone number.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimSwapCreateCheckSimSwap'
        required: true
      responses:
        '200':
          description: Returns whether a SIM swap has been performed during a past period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimSwapCheckSimSwapInfo'
        '400':
          $ref: '#/components/responses/SimSwapGeneric400'
        '401':
          $ref: '#/components/responses/SimSwapGeneric401'
        '403':
          $ref: '#/components/responses/SimSwapGeneric403'
        '404':
          $ref: '#/components/responses/SimSwapGeneric404'
        '422':
          $ref: '#/components/responses/SimSwapGeneric422'
        '500':
          $ref: '#/components/responses/SimSwapGeneric500'
        '503':
          $ref: '#/components/responses/SimSwapGeneric503'
        '504':
          $ref: '#/components/responses/SimSwapGeneric504'
  '/operative/applications/{app_owner_id}/clients/{app_client_id}':
    post:
      tags:
        - Applications
      summary: Creates an application and a client in AuthN.
      description: Creates an application and a client in AuthN.
      operationId: createApplicationAndClient
      parameters:
        - name: app_owner_id
          in: path
          required: true
          schema:
            type: string
            example: 066CRypjNZHx2WZMRk7g
        - name: app_client_id
          in: path
          required: true
          schema:
            type: string
            example: D6XWjIKFLYTN2XDNqdft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperativeCreateApplicationRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperativeApplicationClientResponse'
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
    get:
      tags:
        - Applications
      summary: Get an application and a client by AppOwnerId and AppClientId.
      description: Returns the information of the application and the associated client.
      operationId: getApplications
      parameters:
        - name: app_owner_id
          in: path
          required: true
          schema:
            type: string
            example: owner123
        - name: app_client_id
          in: path
          required: true
          schema:
            type: string
            example: client456
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperativeApplicationClientResponse'
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
  /operative/applications:
    post:
      tags:
        - Applications
      summary: Create a new application
      description: Creates a new application in AuthN without creating a client
      operationId: createApplication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperativeCreateApplicationRequestNew'
      responses:
        '201':
          description: Application created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperativeCreateApplicationResponse'
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '409':
          $ref: '#/components/responses/OperativeGeneric409'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
  '/operative/applications/{application_id}':
    get:
      tags:
        - Applications
      summary: Get an application by ID
      description: Returns the information of an application
      operationId: getApplicationById
      parameters:
        - name: application_id
          in: path
          required: true
          schema:
            type: string
            example: app123
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperativeApplicationResponse'
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '404':
          $ref: '#/components/responses/OperativeGeneric404'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
    put:
      tags:
        - Applications
      summary: Update an application
      description: Updates an existing application
      operationId: updateApplication
      parameters:
        - name: application_id
          in: path
          required: true
          schema:
            type: string
            example: app123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperativeUpdateApplicationRequest'
      responses:
        '200':
          description: Application updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperativeApplicationResponse'
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '404':
          $ref: '#/components/responses/OperativeGeneric404'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
    delete:
      tags:
        - Applications
      summary: Delete an application
      description: Deletes an existing application
      operationId: deleteApplication
      parameters:
        - name: application_id
          in: path
          required: true
          schema:
            type: string
            example: app123
      responses:
        '204':
          description: Application deleted successfully
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '404':
          $ref: '#/components/responses/OperativeGeneric404'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
  '/operative/applications/{app_owner_id}/clients/{app_client_id}/product-orders':
    post:
      tags:
        - Applications
      summary: Create a new product order for a client to consume the Open Gateway APIs
      description: >-
        Create a new product order by specifying the scope and purpose of the
        API to be consumed
      operationId: grantApplicationScopes
      parameters:
        - name: app_owner_id
          in: path
          required: true
          schema:
            type: string
            example: 066CRypjNZHx2WZMRk7g
        - name: app_client_id
          in: path
          required: true
          schema:
            type: string
            example: D6XWjIKFLYTN2XDNqdft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperativeCreateProductOrderRequest'
      responses:
        '201':
          description: Successful operation
          content: {}
        '400':
          $ref: '#/components/responses/OperativeGeneric400'
        '401':
          $ref: '#/components/responses/OperativeGeneric401'
        '403':
          $ref: '#/components/responses/OperativeGeneric403'
        '500':
          $ref: '#/components/responses/OperativeGeneric500'
        '503':
          $ref: '#/components/responses/OperativeGeneric503'
        '504':
          $ref: '#/components/responses/OperativeGeneric504'
  '/orgs/{org_id}/capabilities':
    post:
      operationId: createCapability
      summary: Create a new capability
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogCreateCapabilityRequest'
      responses:
        '201':
          description: Capability created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogCapabilityResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    get:
      operationId: listCapabilities
      summary: Retrieve all capabilities
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: name
          in: query
          required: false
          description: Filter capabilities by name
          schema:
            type: string
      responses:
        '200':
          description: List of capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogCapabilityListResponse'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/capabilities/{id}':
    get:
      operationId: getCapability
      summary: Retrieve a specific capability by ID
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Capability found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogCapabilityResponse'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    put:
      operationId: updateCapability
      summary: Update an existing capability
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogUpdateCapabilityRequest'
      responses:
        '200':
          description: Capability updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogCapabilityResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    delete:
      operationId: deleteCapability
      summary: Delete a capability
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Capability deleted successfully
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/capabilities/{id}/views':
    get:
      operationId: getCapabilityViews
      summary: Get all views associated with a capability
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of views associated with the capability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogViewListResponse'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    post:
      operationId: addViewToCapability
      summary: Associate a view with a capability
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogAddViewToCapabilityRequest'
      responses:
        '201':
          description: View successfully associated with capability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogAddViewToCapabilityResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/capabilities/{id}/views/{view_id}':
    delete:
      operationId: removeViewFromCapability
      summary: Remove view from capability
      tags:
        - Capabilities
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
        - name: view_id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: View successfully removed from capability
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/views':
    post:
      operationId: createView
      summary: Create a new view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogCreateViewRequest'
      responses:
        '201':
          description: View created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogViewResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    get:
      operationId: listViews
      summary: Retrieve all views
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: visibility
          in: query
          required: false
          description: Filter by visibility status
          schema:
            type: boolean
        - name: languageCode
          in: query
          required: false
          description: 'Filter by language code (e.g., es-ES, eu-ES, en-US)'
          schema:
            type: string
            example: es-ES
      responses:
        '200':
          description: List of views
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogViewListResponse'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/views/{id}':
    get:
      operationId: getView
      summary: Retrieve a specific view by ID
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: View found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogViewResponse'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    put:
      operationId: updateView
      summary: Update an existing view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogUpdateViewRequest'
      responses:
        '200':
          description: View updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogViewResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    delete:
      operationId: deleteView
      summary: Delete a view (cascade delete translations and associations)
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: View deleted successfully
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/views/{id}/capabilities':
    get:
      operationId: getViewCapabilities
      summary: Get all capabilities associated with a view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of capabilities associated with the view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogCapabilityListResponse'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    post:
      operationId: addCapabilityToView
      summary: Associate a capability with a view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogAddCapabilityToViewRequest'
      responses:
        '201':
          description: Capability successfully associated with view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogAddCapabilityToViewResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/views/{id}/capabilities/{capability_id}':
    delete:
      operationId: removeCapabilityFromView
      summary: Remove capability from view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
        - name: capability_id
          in: path
          required: true
          description: Capability ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Capability successfully removed from view
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/views/{id}/translations':
    post:
      operationId: addTranslationToView
      summary: Add a translation to a view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogCreateTranslationRequest'
      responses:
        '201':
          description: Translation successfully added to view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogTranslationResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    get:
      operationId: getViewTranslations
      summary: Get all translations for a view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of translations for the view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogTranslationListResponse'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  '/orgs/{org_id}/views/{id}/translations/{language_code}':
    get:
      operationId: getViewTranslationByLanguage
      summary: Get a specific translation by language code
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
        - name: language_code
          in: path
          required: true
          description: 'Language code (e.g., es-ES, eu-ES, en-US)'
          schema:
            type: string
      responses:
        '200':
          description: Translation found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogTranslationResponse'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    put:
      operationId: updateViewTranslation
      summary: Update a translation for a view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
        - name: language_code
          in: path
          required: true
          description: 'Language code (e.g., es-ES, eu-ES, en-US)'
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogUpdateTranslationRequest'
      responses:
        '200':
          description: Translation updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogTranslationResponse'
        '400':
          $ref: '#/components/responses/CatalogBadRequest'
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
    delete:
      operationId: deleteViewTranslation
      summary: Delete a translation from a view
      tags:
        - Views
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          description: View ID (UUID)
          schema:
            type: string
            format: uuid
        - name: language_code
          in: path
          required: true
          description: 'Language code (e.g., es-ES, eu-ES, en-US)'
          schema:
            type: string
      responses:
        '204':
          description: Translation deleted successfully
        '404':
          $ref: '#/components/responses/CatalogNotFound'
        '500':
          $ref: '#/components/responses/CatalogInternalServerError'
  /tenant-catalog/provisioned-tenants:
    get:
      operationId: listProvisionedTenants
      summary: 'List provisioned tenants, optionally filtered by stack'
      description: >-
        Returns the list of tenant identifiers that currently have a provisioned
        schema in the

        Open Gateway database. Each tenant corresponds to a PostgreSQL schema
        prefixed with

        `opengateway_`. When the `stack` query parameter is provided, only
        tenants configured as

        belonging to that stack are returned.
      tags:
        - TenantCatalog
      parameters:
        - name: stack
          in: query
          required: false
          description: >-
            When provided, restricts the result to tenants that belong to this
            stack, according

            to the tenant→stack mapping configured in this service (see its
            configuration

            documentation). If omitted, all provisioned tenants are returned.
          schema:
            type: string
          example: mas-stack
      responses:
        '200':
          description: List of tenant identifiers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantCatalogTenantsResponse'
              example:
                tenants:
                  - tenant1
                  - tenant2
                total: 2
        '500':
          $ref: '#/components/responses/TenantCatalogInternalServerError'
  /product-orders:
    post:
      operationId: createProductOrder
      summary: Create a new product order
      tags:
        - Product Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/ProductOrderCatalogCreateProductOrderRequest
      responses:
        '201':
          description: Product order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductOrderCatalogProductOrderResponse'
        '400':
          $ref: '#/components/responses/ProductOrderCatalogBadRequest'
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
    get:
      operationId: listProductOrders
      summary: List product orders
      tags:
        - Product Orders
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ProductOrderCatalogProductOrderState'
        - name: appOwnerId
          in: query
          required: false
          schema:
            type: string
        - name: appClientId
          in: query
          required: false
          schema:
            type: string
        - name: createdFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: createdTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: List of product orders
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ProductOrderCatalogProductOrderListResponse
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
  '/product-orders/{id}':
    get:
      operationId: getProductOrder
      summary: Retrieve a specific product order by ID
      tags:
        - Product Orders
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Product order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductOrderCatalogProductOrderResponse'
        '404':
          $ref: '#/components/responses/ProductOrderCatalogNotFound'
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
    patch:
      operationId: updateProductOrder
      summary: Update a product order
      tags:
        - Product Orders
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/ProductOrderCatalogUpdateProductOrderRequest
      responses:
        '200':
          description: Product order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductOrderCatalogProductOrderResponse'
        '400':
          $ref: '#/components/responses/ProductOrderCatalogBadRequest'
        '404':
          $ref: '#/components/responses/ProductOrderCatalogNotFound'
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
  '/product-orders/{id}/status':
    get:
      operationId: listProductOrderStatus
      summary: List the per-tenant status of a product order
      tags:
        - Product Order Status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of product order status across tenants
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ProductOrderCatalogProductOrderStatusListResponse
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
  '/orgs/{org_id}/product-orders/{id}/status':
    post:
      operationId: createProductOrderStatus
      summary: Create a product order status entry for a tenant
      tags:
        - Product Order Status
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/ProductOrderCatalogCreateProductOrderStatusRequest
      responses:
        '201':
          description: Product order status created successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ProductOrderCatalogProductOrderStatusResponse
        '400':
          $ref: '#/components/responses/ProductOrderCatalogBadRequest'
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
  '/orgs/{org_id}/product-order-status/{status_id}':
    patch:
      operationId: updateProductOrderStatus
      summary: Update a product order status entry for a tenant
      tags:
        - Product Order Status
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: status_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/ProductOrderCatalogUpdateProductOrderStatusRequest
      responses:
        '200':
          description: Product order status updated successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ProductOrderCatalogProductOrderStatusResponse
        '400':
          $ref: '#/components/responses/ProductOrderCatalogBadRequest'
        '404':
          $ref: '#/components/responses/ProductOrderCatalogNotFound'
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
    delete:
      operationId: deleteProductOrderStatus
      summary: Delete a product order status entry for a tenant
      tags:
        - Product Order Status
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: status_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Product order status deleted successfully
        '404':
          $ref: '#/components/responses/ProductOrderCatalogNotFound'
        '500':
          $ref: '#/components/responses/ProductOrderCatalogInternalServerError'
  '/orgs/{org_id}/qos-profiles/retrieve-qos-profiles':
    post:
      tags:
        - QoSProfiles
      summary: Retrieve QoS profiles
      description: >
        Returns all QoS Profiles that match the given criteria.

        **NOTES:**

        - The access token may be either a 2-legged or 3-legged access token.

        - If the access token is 3-legged, all returned QoS Profiles will be
        available to the subject (device) associated with the access token.

        - If the access token is 2-legged and a device filter is provided, all
        returned QoS Profiles will be available to that device. If multiple
        device identifiers are provided within the device property, only QoS
        Profiles available to the device identifier chosen by the implementation
        will be returned, even if the identifiers do not match the same device.
        API provider does not perform any logic to validate/correlate that the
        indicated device identifiers match the same device. No error should be
        returned if the identifiers are otherwise valid to prevent API consumers
        correlating different identifiers with a given end user.

        - This call uses the POST method instead of GET to comply with the
        CAMARA Commonalities guidelines for sending sensitive or complex data in
        API calls. Since the device field may contain personally identifiable
        information, it should not be sent via GET. Additionally, this call may
        include complex data structures.
          [CAMARA API Design Guidelines](https://github.com/camaraproject/Commonalities/blob/r3.3/documentation/API-design-guidelines.md#post-or-get-for-transferring-sensitive-or-complex-data)
      operationId: retrieveQoSProfiles
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        description: Parameters to query QoS Profiles for a given device
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QoSProfilesQosProfileDeviceRequest'
        required: true
      responses:
        '200':
          description: Contains information about QoS Profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/QoSProfilesQosProfile'
              examples:
                List of QoS Profiles:
                  $ref: '#/components/examples/QoSProfilesLIST_OF_QOS_PROFILES'
        '400':
          $ref: '#/components/responses/QoSProfilesGeneric400'
        '401':
          $ref: '#/components/responses/QoSProfilesGeneric401'
        '403':
          $ref: '#/components/responses/QoSProfilesGeneric403'
        '404':
          $ref: '#/components/responses/QoSProfilesGeneric404'
        '422':
          $ref: '#/components/responses/QoSProfilesGeneric422'
        '429':
          $ref: '#/components/responses/QoSProfilesGeneric429'
  '/orgs/{org_id}/qos-profiles/{name}':
    get:
      tags:
        - QoSProfiles
      summary: Get QoS Profile for a given name
      operationId: getQoSProfile
      description: >
        Returns a QoS Profile that matches the given name.


        The access token may be either a 2-legged or 3-legged access token. If
        the access token is 3-legged, a QoS Profile is only returned if
        available to all subjects associated with the access token.
      parameters:
        - name: name
          in: path
          description: Qos Profile name
          required: true
          schema:
            $ref: '#/components/schemas/QoSProfilesQosProfileName'
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
        - name: phoneNumber
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/QoSProfilesPhoneNumber'
      responses:
        '200':
          description: Contains information about QoS Profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QoSProfilesQosProfile'
        '400':
          $ref: '#/components/responses/QoSProfilesGeneric400'
        '401':
          $ref: '#/components/responses/QoSProfilesGeneric401'
        '403':
          $ref: '#/components/responses/QoSProfilesGeneric403'
        '404':
          $ref: '#/components/responses/QoSProfilesGeneric404'
        '429':
          $ref: '#/components/responses/QoSProfilesGeneric429'
  '/orgs/{org_id}/quality-on-demand/sessions':
    post:
      tags:
        - QoD
      summary: Creates a new session
      description: >
        Create QoS Session to manage latency/throughput priorities


        If the qosStatus in the API response is "AVAILABLE" and a notification
        callback is provided the API consumer will receive in addition to the
        response a

        `QOS_STATUS_CHANGED` event notification with `qosStatus` as `AVAILABLE`.


        If the `qosStatus` in the API response is `REQUESTED`, the client will
        receive either

        - a `QOS_STATUS_CHANGED` event notification with `qosStatus` as
        `AVAILABLE` after the network notifies that it has created the requested
        session, or

        - a `QOS_STATUS_CHANGED` event notification with `qosStatus` as
        `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` after the network
        notifies that it has failed to provide the requested session.


        A `QOS_STATUS_CHANGED` event notification with `qosStatus` as
        `UNAVAILABLE` will also be send if the network terminates the session
        before the requested duration expired


        **NOTES:**

        - In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as
        `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of
        the QoS session are not directly released, but will get deleted
        automatically at earliest 360 seconds after the event.

          This behavior allows API consumers which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a API consumer can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
        - The access token may be either 2-legged or 3-legged. See "Identifying
        the device from the access token" for further information
          - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.
          - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.
      operationId: createSession
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        description: Parameters to create a new session
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QoDCreateSession'
        required: true
      callbacks:
        notifications:
          '{$request.body#/sink}':
            post:
              tags:
                - Session notifications callback
              summary: Session notifications callback
              description: >
                Important: this endpoint is to be implemented by the API
                consumer.

                The API provider will call this endpoint whenever any QoS
                session change (e.g. network termination) related event occurs.

                Currently only QOS_STATUS_CHANGED event is defined.
              operationId: postNotification
              parameters:
                - $ref: '#/components/parameters/QoDx-correlator'
              requestBody:
                required: true
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: '#/components/schemas/QoDCloudEvent'
                    examples:
                      QOS_STATUS_CHANGED_EXAMPLE:
                        $ref: '#/components/examples/QoDQOS_STATUS_CHANGED_EXAMPLE'
              responses:
                '204':
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: '#/components/headers/QoDx-correlator'
                '400':
                  $ref: '#/components/responses/QoDGeneric400'
                '401':
                  $ref: '#/components/responses/QoDGeneric401'
                '403':
                  $ref: '#/components/responses/QoDGeneric403'
                '410':
                  $ref: '#/components/responses/QoDGeneric410'
              security:
                - {}
                - notificationsBearerAuth: []
      responses:
        '201':
          description: Session created
          headers:
            x-correlator:
              $ref: '#/components/headers/QoDx-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QoDSessionInfo'
              examples:
                Successful Session Creation:
                  $ref: '#/components/examples/QoDSESSION_CREATION_EXAMPLE'
                Successful Session Creation With Device Disambiguation:
                  $ref: >-
                    #/components/examples/QoDSESSION_CREATION_EXAMPLE_WITH_DEVICE_RESPONSE
        '400':
          $ref: '#/components/responses/QoDGeneric400'
        '401':
          $ref: '#/components/responses/QoDGeneric401'
        '403':
          $ref: '#/components/responses/QoDGeneric403'
        '404':
          $ref: '#/components/responses/QoDGeneric404'
        '409':
          $ref: '#/components/responses/QoDGeneric409'
        '422':
          $ref: '#/components/responses/QoDGeneric422'
        '429':
          $ref: '#/components/responses/QoDGeneric429'
  '/orgs/{org_id}/quality-on-demand/sessions/{sessionId}':
    get:
      tags:
        - QoD
      summary: Get QoS session information
      description: >
        Querying for QoS session resource information details


        **NOTES:**

        - The access token may be either 2-legged or 3-legged.

        - If a 3-legged access token is used, the end user (and device)
        associated with the session must also be associated with the access
        token.

        - The session must have been created by the same API client given in the
        access token
      operationId: getSession
      parameters:
        - name: sessionId
          in: path
          description: Session ID that was obtained from the createSession operation
          required: true
          schema:
            $ref: '#/components/schemas/QoDSessionId'
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      responses:
        '200':
          description: Contains information about active session
          headers:
            x-correlator:
              $ref: '#/components/headers/QoDx-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QoDSessionInfo'
              examples:
                SESSION_AVAILABLE:
                  $ref: '#/components/examples/QoDSESSION_AVAILABLE_EXAMPLE'
                SESSION_UNAVAILABLE:
                  $ref: '#/components/examples/QoDSESSION_UNAVAILABLE_EXAMPLE'
        '400':
          $ref: '#/components/responses/QoDGeneric400'
        '401':
          $ref: '#/components/responses/QoDGeneric401'
        '403':
          $ref: '#/components/responses/QoDGeneric403'
        '404':
          $ref: '#/components/responses/QoDGeneric404'
        '429':
          $ref: '#/components/responses/QoDGeneric429'
    delete:
      tags:
        - QoD
      summary: Delete a QoD session
      description: >
        Release resources related to QoS session


        If the notification callback is provided and the `qosStatus` of the
        session was `AVAILABLE` the client will receive in addition to the
        response a `QOS_STATUS_CHANGED` event with

        - `qosStatus` as `UNAVAILABLE` and

        - `statusInfo` as `DELETE_REQUESTED`

        There will be no notification event if the `qosStatus` was already
        `UNAVAILABLE`.


        **NOTES:**

        - The access token may be either 2-legged or 3-legged.

        - If a 3-legged access token is used, the subject associated with the
        session must also be associated with the access token.

        - The session must have been created by the same API consumer given in
        the access token
      operationId: deleteSession
      parameters:
        - name: sessionId
          in: path
          description: Session ID that was obtained from the createSession operation
          required: true
          schema:
            $ref: '#/components/schemas/QoDSessionId'
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      responses:
        '204':
          description: Session deleted
          headers:
            x-correlator:
              $ref: '#/components/headers/QoDx-correlator'
        '400':
          $ref: '#/components/responses/QoDGeneric400'
        '401':
          $ref: '#/components/responses/QoDGeneric401'
        '403':
          $ref: '#/components/responses/QoDGeneric403'
        '404':
          $ref: '#/components/responses/QoDGeneric404'
        '429':
          $ref: '#/components/responses/QoDGeneric429'
  '/orgs/{org_id}/quality-on-demand/sessions/{sessionId}/extend':
    post:
      tags:
        - QoD
      summary: Extend the duration of an active session
      description: >
        Extend the overall session duration of an active QoS session (with
        qosStatus = AVAILABLE).

        The overall duration of the QoS session, including the additional
        extended duration, shall not exceed the maximum duration limit fixed for
        the QoS Profile. If the current duration plus the value of
        `requestedAdditionalDuration` exceeds the maximum limit, the new overall
        duration shall be capped to the maximum value allowed.

        An example: For a QoS profile limited to a `maxDuration` of 50,000
        seconds, a QoD session was originally created with duration 30,000
        seconds. Before the session expires, the developer requests to extend
        the session by another 30,000 seconds:

        - Previous duration: 30,000 seconds

        - Requested additional duration: 30,000 seconds

        - New overall session duration: 50,000 seconds (the maximum allowed)


        **NOTES:**

        - The access token may be either 2-legged or 3-legged.

        - If a 3-legged access token is used, the subject associated with the
        session must also be associated with the access token.

        - The session must have been created by the same API consumer given in
        the access token
      operationId: extendQoDSessionDuration
      parameters:
        - name: sessionId
          in: path
          description: Session ID that was obtained from the createSession operation
          required: true
          schema:
            $ref: '#/components/schemas/QoDSessionId'
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        description: Parameters to extend the duration of an active session
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QoDExtendSessionDuration'
        required: true
      responses:
        '200':
          description: Contains information about active session
          headers:
            x-correlator:
              $ref: '#/components/headers/QoDx-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QoDSessionInfo'
        '400':
          $ref: '#/components/responses/QoDGeneric400'
        '401':
          $ref: '#/components/responses/QoDGeneric401'
        '403':
          $ref: '#/components/responses/QoDGeneric403'
        '404':
          $ref: '#/components/responses/QoDGeneric404'
        '409':
          $ref: '#/components/responses/QoDGeneric409'
        '429':
          $ref: '#/components/responses/QoDGeneric429'
  '/orgs/{org_id}/quality-on-demand/retrieve-sessions':
    post:
      tags:
        - QoD
      summary: Get QoD session information for a device
      description: >
        Querying for QoS session resource information details for a device


        **NOTES:**

        - The access token may be either 2-legged or 3-legged.
          - If a 3-legged access token is used, the subject associated with the session must also be associated with the access token. In this case the optional `device` parameter MUST NOT be provided in the request.
          - If a 2-legged access token is used, the device parameter must be provided and identify a device.
        - The session must have been created by the same API consumer given in
        the access token

        - If no QoS session is found for the requested device, an empty array is
        returned.

        - This call uses the POST method instead of GET to comply with the
        CAMARA Commonalities guidelines for sending sensitive or complex data in
        API calls. Since the device field may contain personally identifiable
        information, it should not be sent via GET.
          [CAMARA API Design Guidelines](https://github.com/camaraproject/Commonalities/blob/r3.3/documentation/CAMARA-API-Design-Guide.md#65-post-or-get-for-transferring-sensitive-or-complex-data)
      operationId: retrieveSessionsByDevice
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            example: masmovil
      requestBody:
        description: Parameters to get QoS session information by device
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QoDRetrieveSessionsInput'
        required: true
      responses:
        '200':
          description: >-
            Returns the QoS sessions information for a given device. A device
            may have multiple sessions, thus the response is an array. An empty
            array is returned if no sessions are found.
          headers:
            x-correlator:
              $ref: '#/components/headers/QoDx-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QoDRetrieveSessionsOutput'
              examples:
                RETRIEVE_SESSIONS_ONE_ITEM:
                  $ref: '#/components/examples/QoDRETRIEVE_SESSIONS_EXAMPLE'
                RETRIEVE_SESSIONS_ONE_ITEM_WITH_DEVICE_DISAMBIGUATION_REQUIRED:
                  $ref: >-
                    #/components/examples/QoDRETRIEVE_SESSIONS_EXAMPLE_WITH_DEVICE_RESPONSE
                RETRIEVE_SESSIONS_NO_ITEMS:
                  $ref: '#/components/examples/QoDRETRIEVE_SESSIONS_EMPTY_EXAMPLE'
        '400':
          $ref: '#/components/responses/QoDGeneric400'
        '401':
          $ref: '#/components/responses/QoDGeneric401'
        '403':
          $ref: '#/components/responses/QoDGeneric403'
        '404':
          $ref: '#/components/responses/QoDGeneric404'
        '422':
          $ref: '#/components/responses/QoDGeneric422'
        '429':
          $ref: '#/components/responses/QoDGeneric429'
components:
  schemas:
    ConsentsCreateRequest:
      type: object
      description: Payload to create the consent.
      required:
        - client
        - scope
        - purpose
      properties:
        client:
          description: Application that makes the request to consume the capacity.
          type: string
          example: Vinted_aggr1
        scope:
          description: capabilities to be consumed
          type: string
          example: sim-swap
        purpose:
          description: purpose for which the capability is to be consumed
          type: string
          example: 'dpv:Advertising'
    ConsentsValidateRequest:
      type: object
      description: Payload to validate the consents.
      required:
        - msisdn
        - client
        - purpose
        - scopes
      properties:
        msisdn:
          type: string
          pattern: '^(\+[1-9][0-9]{1,3})?[0-9]{6,14}$'
          example: '+123456789'
          description: >-
            A public identifier addressing a telephone subscription. In mobile
            networks it corresponds to the MSISDN (Mobile Station International
            Subscriber Directory Number). In order to be globally unique it has
            to be formatted in international format, according to E.164
            standard, prefixed with '+'.
        client:
          description: Application that makes the request to consume the capacity.
          type: string
          example: youtube
        purpose:
          description: >-
            Purpose for which the capability is to be consumed. Typically this
            will start with 'dpv:' followed by a value from the Data Privacy
            Vocabulary (DPV) ontology.
          type: string
          example: 'dpv:Advertising'
        scopes:
          description: Capabilities to be consumed
          type: array
          minItems: 1
          items:
            type: string
            example: sim-swap
          example:
            - sim-swap
            - 'number-verification:verify'
            - 'kyc-match:match'
    ConsentsValidateResponse:
      type: object
      description: Consents validate result
      required:
        - isValid
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the consent combining scope, purpose,
            aggregator and application
          example: SimSwap_FraudPreventionAndDetection_Agregador1App1
        scope:
          type: string
          description: Capability to be consumed
          example: sim-swap
        status:
          type: string
          description: Consent status
          enum:
            - ACCEPTED
            - PENDING
            - REVOKED
            - OBJECTED
            - UNKNOWN
            - EXPIRED
          example: ACCEPTED
        expiration_date:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO-8601 timestamp (UTC) indicating when this consent expires.
            Omitted when the consent has no expiration date.
          example: '2025-12-31T23:59:59'
      example:
        - id: SimSwap_FraudPreventionAndDetection_Agregador1App1
          scope: sim-swap
          status: ACCEPTED
          expiration_date: '2025-12-31T23:59:59'
        - id: NumberVerification_FraudPreventionAndDetection_Agregador2App2
          scope: 'number-verification:verify'
          status: EXPIRED
          expiration_date: '2024-01-01T00:00'
    ConsentsApiError:
      required:
        - code
        - details
        - ref
        - title
      type: object
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
    NumberVerificationVerifyRequest:
      type: object
      description: Payload to verify the phone number.
      required:
        - referenceMsisdn
        - evidence
      properties:
        referenceMsisdn:
          type: string
          pattern: '^\+[1-9][0-9]{4,14}$'
          example: '+123456789'
          description: >-
            The MSISDN assigned by the network and extracted from the
            authentication token. A public identifier addressing a telephone
            subscription. In mobile networks it corresponds to the MSISDN
            (Mobile Station International Subscriber Directory Number). In order
            to be globally unique it has to be formatted in international
            format, according to E.164 standard, prefixed with '+'.
        evidence:
          type: object
          properties:
            type:
              type: string
              description: >
                Type of evidence provided:

                - `PLAIN`: The MSISDN is provided in plain text.

                - `HASHED_SHA256`: The MSISDN is provided as a hashed value.
                SHA-256 (in hexadecimal representation) of the mobile phone
                number in **E.164 format (starting with country code)**.
                Prefixed with '+'.
              enum:
                - PLAIN
                - HASHED_SHA256
            value:
              type: string
              description: >
                A public identifier addressing a telephone subscription. In
                mobile networks it corresponds to the MSISDN (Mobile Station
                International Subscriber Directory Number).

                In order to be globally unique, it has to be formatted in
                international format, according to the E.164 standard, prefixed
                with '+'.
          required:
            - type
            - value
    NumberVerificationMatchResponse:
      type: object
      description: Number verification result
      required:
        - devicePhoneNumberVerified
      properties:
        devicePhoneNumberVerified:
          $ref: '#/components/schemas/NumberVerificationDevicePhoneNumberVerified'
    NumberVerificationDevicePhoneNumberVerified:
      description: 'Number verification. True, if it matches'
      type: boolean
    NumberVerificationNumberVerificationShareResponse:
      type: object
      description: Number verification share result
      required:
        - devicePhoneNumber
      properties:
        devicePhoneNumber:
          $ref: '#/components/schemas/NumberVerificationDevicePhoneNumber'
    NumberVerificationDevicePhoneNumber:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+123456789'
      description: >-
        A public identifier addressing a telephone subscription. In mobile
        networks it corresponds to the MSISDN (Mobile Station International
        Subscriber Directory Number). In order to be globally unique it has to
        be formatted in international format, according to E.164 standard,
        prefixed with '+'.
    NumberVerificationApiError:
      required:
        - code
        - details
        - ref
        - title
      type: object
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
    SimSwapSimSwapInfo:
      type: object
      required:
        - latestSimChange
      properties:
        latestSimChange:
          type: string
          format: date-time
          description: >-
            Timestamp of latest SIM swap performed. It must follow [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and
            must have time zone. Recommended format is
            yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows
            2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
          nullable: true
          example: '2023-07-03T14:27:08.312+02:00'
    SimSwapCheckSimSwapInfo:
      type: object
      required:
        - swapped
      properties:
        swapped:
          type: boolean
          description: >-
            Indicates whether the SIM card has been swapped during the period
            within the provided age.
    SimSwapPhoneNumber:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+346661113334'
      description: >-
        A public identifier addressing a telephone subscription. In mobile
        networks it corresponds to the MSISDN (Mobile Station International
        Subscriber Directory Number). In order to be globally unique it has to
        be formatted in international format, according to E.164 standard,
        prefixed with '+'.
    SimSwapCreateCheckSimSwap:
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          $ref: '#/components/schemas/SimSwapPhoneNumber'
        maxAge:
          type: integer
          example: 240
          description: |
            Period in hours to be checked for SIM swap.
          format: int32
          minimum: 1
          maximum: 2400
          default: 240
    SimSwapCreateSimSwapDate:
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          $ref: '#/components/schemas/SimSwapPhoneNumber'
    SimSwapApiError:
      required:
        - code
        - details
        - ref
        - title
      type: object
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
    OperativeApplicationClientResponse:
      type: object
      properties:
        appOwnerId:
          type: string
          description: AppOwner identifier.
        client:
          $ref: '#/components/schemas/OperativeClientResponse'
    OperativeClientResponse:
      type: object
      properties:
        appClientId:
          type: string
          description: Client identifier.
    OperativeCreateApplicationRequest:
      type: object
      required:
        - appOwnerName
        - appOwnerDescription
        - appClientSecret
        - appClientDisplayName
        - appClientSystemName
      properties:
        appOwnerName:
          type: string
          description: The Aggregator Name plus the AppOwner ID.
        appOwnerEmail:
          type: string
          format: email
          description: The AppOwner's contactMedium.emailAddress.
        appOwnerDescription:
          type: string
          description: 'Trading Name, organizationType and tax Number.'
        appClientSecret:
          type: string
          description: Application Client Secret.
        appClientRedirectURL:
          type: array
          items:
            type: string
            format: uri
          description: Application redirectURL.
        appClientDisplayName:
          type: string
          description: Application commercialName.
          pattern: '^[^_]*$'
        appClientSystemName:
          type: string
          description: Application systemName.
        appClientJwksUri:
          type: string
          format: uri
          description: Application Client jwks Uri.
    OperativeCreateProductOrderRequest:
      type: object
      required:
        - scope
        - purpose
      properties:
        scope:
          type: string
          description: Defines the scope of the API.
        purpose:
          type: string
          description: Defines the purpose of the API.
    OperativeCreateApplicationRequestNew:
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          type: string
          description: Application identifier
          example: app123
        name:
          type: string
          description: Application name
          example: My Application
        email:
          type: string
          format: email
          description: >-
            Contact email (defaults to gcp-mm-open-gateway@masorange.es if not
            provided)
          example: contact@example.com
        description:
          type: string
          description: Application description
          example: Application for testing purposes
    OperativeUpdateApplicationRequest:
      type: object
      properties:
        name:
          type: string
          description: Updated application name
          example: My Updated Application
        email:
          type: string
          format: email
          description: Updated contact email
          example: newemail@example.com
        description:
          type: string
          description: Updated application description
          example: Updated description
    OperativeCreateApplicationResponse:
      type: object
      properties:
        id:
          type: string
          description: Application identifier
          example: app123
    OperativeApplicationResponse:
      type: object
      properties:
        id:
          type: string
          description: Application identifier
          example: app123
        name:
          type: string
          description: Application name
          example: My Application
        email:
          type: string
          format: email
          description: Contact email
          example: contact@example.com
        description:
          type: string
          description: Application description
          example: Application for testing purposes
    OperativeApiError:
      required:
        - code
        - details
        - ref
        - title
      type: object
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
    CatalogCreateCapabilityRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 100
          description: Name of the capability (CAMARA capability name)
          example: kyc-match
    CatalogUpdateCapabilityRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
          description: Updated name of the capability
          example: sim-swap
    CatalogCapabilityResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Capability ID
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Capability name
          example: kyc-match
    CatalogCapabilityListResponse:
      type: object
      properties:
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/CatalogCapabilityResponse'
        total:
          type: integer
          description: Total number of capabilities
          example: 10
    CatalogTranslation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Translation ID
          example: 550e8400-e29b-41d4-a716-446655440001
        languageCode:
          type: string
          description: 'Language code (es-ES, eu-ES, en-US)'
          example: es-ES
        description:
          type: string
          description: Translated description
          example: Vista de consentimiento para KYC
    CatalogCreateViewRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 100
          description: Name of the view
          example: kyc-consent-view
        orderDisplay:
          type: integer
          description: Display order for the view
          example: 1
        visibility:
          type: boolean
          description: Whether the view is visible
          default: true
          example: true
    CatalogUpdateViewRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
          description: Updated name of the view
          example: kyc-consent-view-updated
        orderDisplay:
          type: integer
          description: Updated display order
          example: 2
        visibility:
          type: boolean
          description: Updated visibility status
          example: false
    CatalogViewResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: View ID
          example: 550e8400-e29b-41d4-a716-446655440002
        name:
          type: string
          description: View name
          example: kyc-consent-view
        orderDisplay:
          type: integer
          description: Display order
          example: 1
        visibility:
          type: boolean
          description: Visibility status
          example: true
        translations:
          type: array
          items:
            $ref: '#/components/schemas/CatalogTranslation'
        capabilityIds:
          type: array
          items:
            type: string
            format: uuid
          description: Associated capability IDs
    CatalogViewListResponse:
      type: object
      properties:
        views:
          type: array
          items:
            $ref: '#/components/schemas/CatalogViewResponse'
        total:
          type: integer
          description: Total number of views
          example: 5
    CatalogAddCapabilityToViewRequest:
      type: object
      required:
        - capabilityId
      properties:
        capabilityId:
          type: string
          format: uuid
          description: Capability ID to associate with the view
          example: 550e8400-e29b-41d4-a716-446655440000
    CatalogAddCapabilityToViewResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Association ID
          example: 650e8400-e29b-41d4-a716-446655440000
        viewId:
          type: string
          format: uuid
          description: View ID
          example: 550e8400-e29b-41d4-a716-446655440002
        capabilityId:
          type: string
          format: uuid
          description: Capability ID
          example: 550e8400-e29b-41d4-a716-446655440000
    CatalogAddViewToCapabilityRequest:
      type: object
      required:
        - viewId
      properties:
        viewId:
          type: string
          format: uuid
          description: View ID to associate with the capability
          example: 550e8400-e29b-41d4-a716-446655440002
    CatalogAddViewToCapabilityResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Association ID
          example: 650e8400-e29b-41d4-a716-446655440000
        capabilityId:
          type: string
          format: uuid
          description: Capability ID
          example: 550e8400-e29b-41d4-a716-446655440000
        viewId:
          type: string
          format: uuid
          description: View ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CatalogCreateTranslationRequest:
      type: object
      required:
        - languageCode
      properties:
        languageCode:
          type: string
          description: 'Language code (e.g., es-ES, eu-ES, en-US)'
          example: es-ES
        description:
          type: string
          description: Translated description
          example: Vista de consentimiento para KYC
    CatalogUpdateTranslationRequest:
      type: object
      properties:
        languageCode:
          type: string
          description: Updated language code
          example: es-ES
        description:
          type: string
          description: Updated translated description
          example: Vista de consentimiento para KYC actualizada
    CatalogTranslationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Translation ID
          example: 550e8400-e29b-41d4-a716-446655440001
        languageCode:
          type: string
          description: Language code
          example: es-ES
        description:
          type: string
          description: Translated description
          example: Vista de consentimiento para KYC
    CatalogTranslationListResponse:
      type: object
      properties:
        translations:
          type: array
          items:
            $ref: '#/components/schemas/CatalogTranslationResponse'
        total:
          type: integer
          description: Total number of translations
          example: 3
    CatalogError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        message:
          type: string
          description: Error message
          example: Invalid input provided
        status:
          type: integer
          description: HTTP status code
          example: 400
    TenantCatalogTenantsResponse:
      type: object
      properties:
        tenants:
          type: array
          items:
            type: string
            description: Tenant identifier (schema suffix after `opengateway_`)
            example: tenant1
        total:
          type: integer
          description: Total number of tenants
          example: 2
    TenantCatalogError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: INTERNAL_ERROR
        message:
          type: string
          description: Error message
          example: An unexpected error occurred
        status:
          type: integer
          description: HTTP status code
          example: 500
    ProductOrderCatalogProductOrderState:
      type: string
      enum:
        - IN_PROGRESS
        - COMPLETED
        - FAILED
    ProductOrderCatalogTenantOrderState:
      type: string
      enum:
        - IN_PROGRESS
        - COMPLETED
        - NOT_SUPPORTED
        - FAILED
    ProductOrderCatalogCreateProductOrderRequest:
      type: object
      required:
        - appOwnerId
        - appClientId
        - scope
        - createdBy
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        appOwnerId:
          type: string
          maxLength: 255
          example: 066CRypjNZHx2WZMRk7g
        appClientId:
          type: string
          maxLength: 255
          example: D6XWjIKFLYTN2XDNqdft
        scope:
          type: string
          maxLength: 255
          example: kyc-match
        purpose:
          type: string
          maxLength: 255
          nullable: true
          example: fraud-prevention
        createdBy:
          type: string
          maxLength: 255
          example: system
    ProductOrderCatalogUpdateProductOrderRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ProductOrderCatalogProductOrderState'
        purpose:
          type: string
          maxLength: 255
          nullable: true
        finishedAt:
          type: string
          format: date-time
          nullable: true
    ProductOrderCatalogProductOrderResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        appOwnerId:
          type: string
        appClientId:
          type: string
        scope:
          type: string
        purpose:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/ProductOrderCatalogProductOrderState'
        createdAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
          nullable: true
        createdBy:
          type: string
    ProductOrderCatalogProductOrderListResponse:
      type: object
      properties:
        productOrders:
          type: array
          items:
            $ref: '#/components/schemas/ProductOrderCatalogProductOrderResponse'
        total:
          type: integer
        page:
          type: integer
        size:
          type: integer
    ProductOrderCatalogCreateProductOrderStatusRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/ProductOrderCatalogTenantOrderState'
    ProductOrderCatalogUpdateProductOrderStatusRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/ProductOrderCatalogTenantOrderState'
    ProductOrderCatalogProductOrderStatusResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        productOrderId:
          type: string
          format: uuid
        tenant:
          type: string
        status:
          $ref: '#/components/schemas/ProductOrderCatalogTenantOrderState'
    ProductOrderCatalogProductOrderStatusListResponse:
      type: object
      properties:
        status:
          type: array
          items:
            $ref: '#/components/schemas/ProductOrderCatalogProductOrderStatusResponse'
        total:
          type: integer
    ProductOrderCatalogError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        message:
          type: string
          description: Error message
          example: Invalid input provided
        status:
          type: integer
          description: HTTP status code
          example: 400
    QoSProfilesQosProfile:
      description: |
        Data type with attributes of a QosProfile
      type: object
      properties:
        name:
          $ref: '#/components/schemas/QoSProfilesQosProfileName'
        description:
          description: |
            A description of the QoS profile.
          type: string
          example: QoS profile for video streaming
        status:
          $ref: '#/components/schemas/QoSProfilesQosProfileStatusEnum'
        countryAvailability:
          description: >
            A list of countries, and optionally networks, for which the API
            provider makes the profile available.

            - When profiles are filtered for a specific device (i.e. using a
            3-legged access token or an explicit device filter parameter), the
            profile can be used by that device in any of these countries when
            connected to any of the listed networks (assuming roaming is
            permitted for networks that are not the device's home network), or
            the API provider's own network if no networks are listed

            - When there is no device filter, availability for a given country
            means that the QoS profile may be available to some devices
            connected to the listed networks in that country (or to the API
            provider’s default network if none are listed). However, this does
            not imply that the profile is available to all devices, or that a
            particular device will be able to use the profile across all listed
            countries or networks. In particular, the response does not provide
            enough information to determine availability for roaming for
            specific devices; consumers should query the API with a specific
            device identifier to get definitive availability.

            - If this field is not present in the QoS profile, no assumption can
            be made about the availability of the profile in any given country
            or for any given network
          allOf:
            - $ref: '#/components/schemas/QoSProfilesAvailability'
        targetMinUpstreamRate:
          description: >
            This is the target minimum upload speed for the QoS profile.

            It represents the minimum rate that the network attempts to deliver.

            Please note that this is a target value—the network might not always
            be able to provide this rate under all conditions.

            It helps ensure that applications like video calls or live streaming
            perform consistently.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesRate'
        maxUpstreamRate:
          description: |
            The maximum best effort data
          allOf:
            - $ref: '#/components/schemas/QoSProfilesRate'
        maxUpstreamBurstRate:
          description: >
            When defined, this is the maximum upstream burst rate for the QoS
            profile, that will enable

            the network to burst data at a higher rate than the maxUpstreamRate
            for a period of time.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesRate'
        targetMinDownstreamRate:
          description: >
            This is the target maximum upload speed for the QoS profile.

            It represents the maximum rate that the network attempts to deliver.

            Please note that this is a target value—the network might not always
            be able to provide this rate under all conditions.

            It helps ensure that applications like video calls or live streaming
            perform consistently.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesRate'
        maxDownstreamRate:
          description: |
            The maximum best effort rate
          allOf:
            - $ref: '#/components/schemas/QoSProfilesRate'
        maxDownstreamBurstRate:
          description: >
            When defined, this is the maximum downstream burst rate for the QoS
            profile, that will enable

            the network to burst data at a higher rate than the
            maxDownstreamRate for a period of time.

            This can result in improved user experience when there is additional
            network capacity.

            For instance, when a user is streaming a video, the network can
            burst data at a higher rate

            to fill the buffer, and then return to the maxUpstreamRate once the
            buffer is full.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesRate'
        minDuration:
          description: |
            The shortest time period that this profile can be deployed.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesDuration'
        maxDuration:
          description: >
            The maximum time period that this profile can be deployed.

            Overall session duration must not exceed this value. This includes
            the initial requested duration plus any extensions.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesDuration'
        priority:
          type: integer
          example: 20
          description: >
            Priority levels allow efficient resource allocation and ensure
            optimal performance

            for various services in each technology, with the highest priority
            traffic receiving

            preferential treatment.

            The lower value the higher priority.

            Not all access networks use the same priority range, so this
            priority will be

            scaled to the access network's priority range.
          format: int32
          minimum: 1
          maximum: 100
        packetDelayBudget:
          description: >
            The packet delay budget is the maximum allowable one-way latency
            between the customer's device

            and the gateway from the operator's network to other networks. By
            limiting the delay, the network

            can provide an acceptable level of performance for various services,
            such as voice calls,

            video streaming, and data.

            The end-to-end or round trip latency will be about two times this
            value plus the latency not controlled

            by the operator
          allOf:
            - $ref: '#/components/schemas/QoSProfilesDuration'
        jitter:
          description: >
            The jitter requirement aims to limit the maximum variation in
            round-trip

            packet delay for the 99th percentile of traffic, following ITU
            Y.1540

            standards. It considers only acknowledged packets in a session,
            which are

            packets that receive a confirmation of receipt from the recipient
            (e.g.,

            using TCP). This requirement helps maintain consistent latency,
            essential

            for real-time applications such as VoIP, video calls, and gaming.
          allOf:
            - $ref: '#/components/schemas/QoSProfilesDuration'
        packetErrorLossRate:
          type: integer
          description: >
            This field specifies the acceptable level of data loss during
            transmission.

            The value is an exponent of 10, so a value of 3 means that up to
            10⁻³, or 0.1%, of the

            data packets may be lost. This setting is part of a broader system
            that categorizes

            different types of network traffic (like phone calls, video streams,
            or data transfers)

            to ensure they perform reliably on the network.
          format: int32
          minimum: 1
          maximum: 10
          example: 3
        l4sQueueType:
          type: string
          enum:
            - non-l4s-queue
            - l4s-queue
            - mixed-queue
          description: >

            **NOTE**: l4sQueueType is experimental and could change or be
            removed in a future release.


            Specifies the type of queue for L4S (Low Latency, Low Loss, Scalable
            Throughput) traffic management. L4S is an advanced queue management
            approach designed to provide ultra-low latency and high throughput
            for internet traffic, particularly beneficial for interactive
            applications such as gaming, video conferencing, and virtual
            reality.


            **Queue Type Descriptions:**


            - **non-l4s-queue**:
              A traditional queue used for legacy internet traffic that does not utilize L4S enhancements. It provides standard latency and throughput levels.

            - **l4s-queue**:
              A dedicated queue optimized for L4S traffic, delivering ultra-low latency, low loss, and scalable throughput to support latency-sensitive applications.

            - **mixed-queue**:
              A shared queue that can handle both L4S and traditional traffic, offering a balance between ultra-low latency for L4S flows and compatibility with non-L4S flows.
          externalDocs:
            description: 'For more details, refer to the L4S standard.'
            url: 'https://datatracker.ietf.org/doc/rfc9330/'
        serviceClass:
          type: string
          description: >

            **NOTE**: serviceClass is experimental and could change or be
            removed in a future release.


            The name of a Service Class, representing a QoS Profile designed to
            provide optimized behavior for a specific application type. While
            DSCP values are commonly associated with Service Classes, their use
            may vary across network segments and may not be applied throughout
            the entire end-to-end QoS session. This aligns with the serviceClass
            concept used in HomeDevicesQoQ for consistent terminology.


            Service classes define specific QoS behaviors that map to DSCP
            (Differentiated Services Code Point) values or Microsoft QoS traffic
            types.


            The supported mappings are:

            1. Values aligned with the
            [RFC4594](https://datatracker.ietf.org/doc/html/rfc4594) guidelines
            for differentiated traffic classes.

            2. Microsoft
            [QOS_TRAFFIC_TYPE](https://learn.microsoft.com/en-us/windows/win32/api/qos2/ne-qos2-qos_traffic_type)
            values for Windows developers.


            **Supported Service Classes**:


            | Service Class Name    | DSCP Name | DSCP value (decimal) | DCSP
            value (binary) | Microsoft Value | Application
            Examples                                                 |

            |-----------------------|-----------|----------------------|---------------------|-----------------|----------------------------------------------------------------------|

            | Microsoft Voice       |    CS7    |          56          |       
            111000       |       4,5       | Microsoft QOSTrafficTypeVoice and
            QOSTrafficTypeControl              |

            | Microsoft Audio/Video |    CS5    |          40          |       
            101000       |       2,3       | Microsoft
            QOSTrafficTypeExcellentEffort and QOSTrafficTypeAudioVideo |

            | Real-Time Interactive |    CS4    |          32          |       
            100000       |                 | Video conferencing and Interactive
            gaming                            |

            | Multimedia Streaming  |    AF31   |          26          |       
            011010       |                 | Streaming video and audio on
            demand                                  |

            | Broadcast Video       |    CS3    |          24          |       
            011000       |                 | Broadcast TV & live
            events                                           |

            | Low-Latency Data      |    AF21   |          18          |       
            010010       |                 | Client/server transactions
            Web-based ordering                        |

            | High-Throughput Data  |    AF11   |          10          |       
            001010       |                 | Store and forward
            applications                                       |

            | Low-Priority Data     |    CS1    |           8          |       
            001000       |        1        | Any flow that has no BW assurance -
            also:                            |

            |                       |           |                     
            |                     |                 | Microsoft
            QOSTrafficTypeBackground                                   |

            | Standard              |  DF(CS0)  |           0          |       
            000000       |        0        | Undifferentiated applications -
            also:                                |

            |                       |           |                     
            |                     |                 | Microsoft
            QOSTrafficTypeBestEffort                                   |
          enum:
            - microsoft_voice
            - microsoft_audio_video
            - real_time_interactive
            - multimedia_streaming
            - broadcast_video
            - low_latency_data
            - high_throughput_data
            - low_priority_data
            - standard
          example: real_time_interactive
      required:
        - name
        - status
    QoSProfilesQosProfileName:
      description: >
        A unique name for identifying a specific QoS profile.

        This may follow different formats depending on the service providers
        implementation.

        Some options addresses:
          - A UUID style string
          - Support for predefined profile names like `QOS_E`, `QOS_S`, `QOS_M`, and `QOS_L`
          - A searchable descriptive name
      type: string
      example: voice
      minLength: 3
      maxLength: 256
      pattern: '^[a-zA-Z0-9_.-]+$'
    QoSProfilesRate:
      description: Specification of rate
      type: object
      properties:
        value:
          description: Quantity of rate
          type: integer
          example: 10
          format: int32
          minimum: 0
          maximum: 1024
        unit:
          $ref: '#/components/schemas/QoSProfilesRateUnitEnum'
    QoSProfilesDuration:
      description: Specification of duration
      type: object
      properties:
        value:
          description: Quantity of duration
          type: integer
          example: 12
          format: int32
          minimum: 1
        unit:
          $ref: '#/components/schemas/QoSProfilesTimeUnitEnum'
    QoSProfilesTimeUnitEnum:
      description: Units of time
      type: string
      enum:
        - Days
        - Hours
        - Minutes
        - Seconds
        - Milliseconds
        - Microseconds
        - Nanoseconds
    QoSProfilesQosProfileStatusEnum:
      description: >
        The current status of the QoS Profile

        - `ACTIVE`- QoS Profile is available to be used

        - `INACTIVE`- QoS Profile is not currently available to be deployed

        - `DEPRECATED`- QoS profile is actively being used in a QoD session, but
        can not be deployed in new QoD sessions
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - DEPRECATED
    QoSProfilesRateUnitEnum:
      description: Units of rate
      type: string
      enum:
        - bps
        - kbps
        - Mbps
        - Gbps
        - Tbps
    QoSProfilesQosProfileDeviceRequest:
      description: |
        Request object for QoS Profiles for a given device
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          $ref: '#/components/schemas/QoSProfilesPhoneNumber'
        device:
          $ref: '#/components/schemas/QoSProfilesDevice'
        name:
          $ref: '#/components/schemas/QoSProfilesQosProfileName'
        status:
          $ref: '#/components/schemas/QoSProfilesQosProfileStatusEnum'
    QoSProfilesAvailability:
      description: >-
        A list of countries, and optionally networks, for which the API provider
        makes the profile available
      type: array
      items:
        type: object
        required:
          - countryName
        properties:
          countryName:
            description: >-
              The two letter ISO 3166-2 country code for the country in which
              the QoS profile is available in at least one network
            type: string
            pattern: '^[A-Z]{2}$'
            example: GB
          networks:
            description: >-
              A list of networks within the country for which the QoS profile is
              available from the API provider
            type: array
            items:
              description: >-
                The network identifier. For mobile networks, this is the PLMN
                Identifier (MCC + MNC), which is a 5 or 6 digit integer.
              type: string
              example: '23591'
            example:
              - '23591'
              - '23415'
        example:
          countryName: GB
          networks:
            - '23591'
            - '23415'
      example:
        - countryName: GB
          networks:
            - '23591'
            - '23415'
        - countryName: DE
          networks:
            - '26202'
    QoSProfilesDevice:
      description: >
        End-user equipment able to connect to a mobile network. Examples of
        devices include smartphones or IoT sensors/actuators.


        The developer can choose to provide the below specified device
        identifiers:


        * `ipv4Address`

        * `ipv6Address`

        * `phoneNumber`

        NOTE1: the network operator might support only a subset of these
        options. The API consumer can provide multiple identifiers to be
        compatible across different operators. In this case the identifiers MUST
        belong to the same device.

        NOTE2: as for this Commonalities release, we are enforcing that the
        networkAccessIdentifier is only part of the schema for future-proofing,
        and CAMARA does not currently allow its use. After the CAMARA
        meta-release work is concluded and the relevant issues are resolved, its
        use will need to be explicitly documented in the guidelines.
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/QoSProfilesPhoneNumber'
        networkAccessIdentifier:
          $ref: '#/components/schemas/QoSProfilesNetworkAccessIdentifier'
        ipv4Address:
          $ref: '#/components/schemas/QoSProfilesDeviceIpv4Addr'
        ipv6Address:
          $ref: '#/components/schemas/QoSProfilesDeviceIpv6Address'
      minProperties: 1
    QoSProfilesNetworkAccessIdentifier:
      description: >-
        A public identifier addressing a subscription in a mobile network. In
        3GPP terminology, it corresponds to the GPSI formatted with the External
        Identifier ({Local Identifier}@{Domain Identifier}). Unlike the
        telephone number, the network access identifier is not subjected to
        portability ruling in force, and is individually managed by each
        operator.
      type: string
      example: 123456789@domain.com
    QoSProfilesPhoneNumber:
      description: >-
        A public identifier addressing a telephone subscription. In mobile
        networks it corresponds to the MSISDN (Mobile Station International
        Subscriber Directory Number). In order to be globally unique it has to
        be formatted in international format, according to E.164 standard,
        prefixed with '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+123456789'
    QoSProfilesDeviceIpv4Addr:
      type: object
      description: >
        The device should be identified by either the public (observed) IP
        address and port as seen by the application server, or the private
        (local) and any public (observed) IP addresses in use by the device
        (this information can be obtained by various means, for example from
        some DNS servers).


        If the allocated and observed IP addresses are the same (i.e. NAT is not
        in use) then  the same address should be specified for both
        publicAddress and privateAddress.


        If NAT64 is in use, the device should be identified by its publicAddress
        and publicPort, or separately by its allocated IPv6 address (field
        ipv6Address of the Device object)


        In all cases, publicAddress must be specified, along with at least one
        of either privateAddress or publicPort, dependent upon which is known.
        In general, mobile devices cannot be identified by their public IPv4
        address alone.
      properties:
        publicAddress:
          $ref: '#/components/schemas/QoSProfilesSingleIpv4Addr'
        privateAddress:
          $ref: '#/components/schemas/QoSProfilesSingleIpv4Addr'
        publicPort:
          $ref: '#/components/schemas/QoSProfilesPort'
      anyOf:
        - required:
            - publicAddress
            - privateAddress
        - required:
            - publicAddress
            - publicPort
      example:
        publicAddress: 203.0.113.0
        publicPort: 59765
    QoSProfilesPort:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535
    QoSProfilesSingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: 203.0.113.0
    QoSProfilesDeviceIpv6Address:
      description: >
        The device should be identified by the observed IPv6 address, or by any
        single IPv6 address from within the subnet allocated to the device (e.g.
        adding ::0 to the /64 prefix).


        The session shall apply to all IP flows between the device subnet and
        the specified application server, unless further restricted by the
        optional parameters devicePorts or applicationServerPorts.
      type: string
      format: ipv6
      example: '2001:db8:85a3:8d3:1319:8a2e:370:7344'
    QoSProfilesApiError:
      required:
        - code
        - details
        - ref
        - title
      type: object
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
    QoDXCorrelator:
      description: Correlation id for the different services
      type: string
    QoDSessionId:
      description: Session ID in UUID format
      type: string
      format: uuid
      pattern: >-
        ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
    QoDBaseSessionInfo:
      description: Common attributes of a QoD session
      type: object
      properties:
        applicationServer:
          $ref: '#/components/schemas/QoDApplicationServer'
        devicePorts:
          description: >-
            The ports used locally by the device for flows to which the
            requested QoS profile should apply. If omitted, then the qosProfile
            will apply to all flows between the device and the specified
            application server address and ports
          allOf:
            - $ref: '#/components/schemas/QoDPortsSpec'
        applicationServerPorts:
          description: A list of single ports or port ranges on the application server
          allOf:
            - $ref: '#/components/schemas/QoDPortsSpec'
        qosProfile:
          $ref: '#/components/schemas/QoDQosProfileName'
        sink:
          type: string
          format: uri
          pattern: '^https:\/\/.+$'
          description: >-
            The address to which events about all status changes of the session
            (e.g. session termination) shall be delivered using the selected
            protocol.
          example: 'https://endpoint.example.com/sink'
        sinkCredential:
          description: >-
            A sink credential provides authentication or authorization
            information necessary to enable delivery of events to a target.
          allOf:
            - $ref: '#/components/schemas/QoDSinkCredential'
      required:
        - applicationServer
        - qosProfile
    QoDSessionInfo:
      description: >
        Session related information returned in responses.

        Note that the device object is defined as optional and will only to be
        returned if provided in createSession. If more than one type of device
        identifier was provided, only one identifier will be returned (at
        implementation choice and with the original value provided in
        createSession).

        Please note that IP addresses of devices can change and get reused, so
        the original values may no longer identify the same device. They
        identified the device at the time of session creation.
      allOf:
        - type: object
          properties:
            device:
              description: >-
                Disambiguates the device to which the session applies when
                multiple device identifiers were provided
              allOf:
                - $ref: '#/components/schemas/QoDDeviceResponse'
                - example:
                    phoneNumber: '+123456789'
        - $ref: '#/components/schemas/QoDBaseSessionInfo'
        - type: object
          properties:
            sessionId:
              $ref: '#/components/schemas/QoDSessionId'
            duration:
              description: >
                Session duration in seconds. Implementations can grant the
                requested session duration or set a different duration, based on
                network policies or conditions.

                - When `qosStatus` is "REQUESTED", the value is the duration to
                be scheduled, granted by the implementation.

                - When `qosStatus` is "AVAILABLE", the value is the overall
                duration since `startedAt. When the session is extended, the
                value is the new overall duration of the session.

                - When `qosStatus` is "UNAVAILABLE", the value is the overall
                effective duration since `startedAt` until the session was
                terminated.
              type: integer
              format: int32
              minimum: 1
              example: 3600
            startedAt:
              description: >-
                Date and time when the QoS status became "AVAILABLE". Not to be
                returned when `qosStatus` is "REQUESTED". It must follow [RFC
                3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
                and must have time zone.
              type: string
              format: date-time
              example: '2024-06-01T12:00:00Z'
            expiresAt:
              description: >
                Date and time of the QoS session expiration. It must follow [RFC
                3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
                and must have time zone.

                - When `qosStatus` is "AVAILABLE", it is the limit time when the
                session is scheduled to finnish, if not terminated by other
                means.

                - When `qosStatus` is "UNAVAILABLE", it is the time when the
                session was terminated.

                - Not to be returned when `qosStatus` is "REQUESTED".

                When the session is extended, the value is the new expiration
                time of the session.
              type: string
              format: date-time
              example: '2024-06-01T13:00:00Z'
            qosStatus:
              $ref: '#/components/schemas/QoDQosStatus'
            statusInfo:
              $ref: '#/components/schemas/QoDStatusInfo'
          required:
            - sessionId
            - duration
            - qosStatus
    QoDCreateSession:
      description: Attributes required to create a session
      allOf:
        - type: object
          properties:
            device:
              $ref: '#/components/schemas/QoDDevice'
        - $ref: '#/components/schemas/QoDBaseSessionInfo'
        - type: object
          properties:
            phoneNumber:
              $ref: '#/components/schemas/QoDPhoneNumber'
            duration:
              description: >
                Requested session duration in seconds. Value may be explicitly
                limited for the QoS profile, as specified in the Qos Profile
                (see qos-profile API). Implementations can grant the requested
                session duration or set a different duration, based on network
                policies or conditions.
              type: integer
              format: int32
              minimum: 1
              example: 3600
          required:
            - duration
            - phoneNumber
    QoDPort:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535
    QoDPortsSpec:
      description: Specification of several TCP or UDP ports
      type: object
      minProperties: 1
      properties:
        ranges:
          description: Range of TCP or UDP ports
          type: array
          minItems: 1
          items:
            type: object
            required:
              - from
              - to
            properties:
              from:
                $ref: '#/components/schemas/QoDPort'
              to:
                $ref: '#/components/schemas/QoDPort'
        ports:
          description: Array of TCP or UDP ports
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/QoDPort'
      example:
        ranges:
          - from: 5010
            to: 5020
        ports:
          - 5060
          - 5070
    QoDSinkCredential:
      type: object
      required:
        - credentialType
      properties:
        credentialType:
          type: string
      discriminator:
        propertyName: credentialType
        mapping:
          PLAIN: '#/components/schemas/QoDPlainCredential'
          ACCESSTOKEN: '#/components/schemas/QoDAccessTokenCredential'
          REFRESHTOKEN: '#/components/schemas/QoDRefreshTokenCredential'
      oneOf:
        - $ref: '#/components/schemas/QoDPlainCredential'
        - $ref: '#/components/schemas/QoDAccessTokenCredential'
        - $ref: '#/components/schemas/QoDRefreshTokenCredential'
    QoDPlainCredential:
      type: object
      description: >-
        A plain credential as a combination of an identifier and a secret. MUST
        not be used in this API version.
      required:
        - identifier
        - secret
        - credentialType
      properties:
        credentialType:
          type: string
          enum:
            - PLAIN
          default: PLAIN
        identifier:
          description: The identifier might be an account or username.
          type: string
        secret:
          description: The secret might be a password or passphrase.
          type: string
    QoDAccessTokenCredential:
      type: object
      description: An access token credential.
      required:
        - credentialType
        - accessToken
        - accessTokenExpiresUtc
        - accessTokenType
      properties:
        credentialType:
          type: string
          enum:
            - ACCESSTOKEN
        accessToken:
          description: >-
            REQUIRED. An access token is a previously acquired token granting
            access to the target resource.
          type: string
        accessTokenExpiresUtc:
          type: string
          format: date-time
          description: >
            REQUIRED. An absolute (UTC) timestamp at which the token shall be
            considered expired. Token expiration should occur

            after the termination of the requested session, allowing the client
            to be notified of any changes during the

            sessions's existence. If the token expires while the session is
            still active, the client will stop receiving notifications.

            If the access token is a JWT and registered "exp" (Expiration Time)
            claim is present, the two expiry times should match.

            It must follow [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and
            must have time zone.
          example: '2023-07-03T12:27:08.312Z'
        accessTokenType:
          description: >-
            REQUIRED. Type of the access token (See [OAuth
            2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). For the
            current version of the API the type MUST be set to `Bearer`.
          type: string
          enum:
            - bearer
    QoDRefreshTokenCredential:
      type: object
      description: >-
        An access token credential with a refresh token. MUST not be used in
        this API version.
      required:
        - credentialType
        - accessToken
        - accessTokenExpiresUtc
        - accessTokenType
        - refreshToken
        - refreshTokenEndpoint
      properties:
        credentialType:
          type: string
          enum:
            - REFRESHTOKEN
        accessToken:
          type: string
          description: REQUIRED access token.
        accessTokenExpiresUtc:
          description: >-
            REQUIRED. Type of the access token (See [OAuth
            2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
          type: string
          format: date-time
        accessTokenType:
          type: string
          enum:
            - bearer
        refreshToken:
          type: string
          description: REQUIRED refresh token.
        refreshTokenEndpoint:
          type: string
          format: uri
    QoDExtendSessionDuration:
      description: Attributes required to extend the duration of an active session
      type: object
      properties:
        requestedAdditionalDuration:
          description: >
            Additional duration in seconds to be added to the current session
            duration. The overall session duration, including extensions, shall
            not exceed the maximum duration limit for the QoS Profile.
          type: integer
          format: int32
          minimum: 1
          example: 1800
      required:
        - requestedAdditionalDuration
    QoDQosProfileName:
      description: >
        A unique name for identifying a specific QoS profile.

        This may follow different formats depending on the API provider
        implementation.

        Some options addresses:
          - A UUID style string
          - Support for predefined profiles QOS_S, QOS_M, QOS_L, and QOS_E
          - A searchable descriptive name
        The set of QoS Profiles that an API provider is offering may be
        retrieved by means of the QoS Profile API (qos-profile) or agreed on
        onboarding time.
      type: string
      example: voice
      minLength: 3
      maxLength: 256
      pattern: '^[a-zA-Z0-9_.-]+$'
    QoDCloudEvent:
      description: Event compliant with the CloudEvents specification
      required:
        - id
        - source
        - specversion
        - type
        - time
      properties:
        id:
          description: 'Identifier of this event, that must be unique in the source context.'
          type: string
        source:
          description: >-
            Identifies the context in which an event happened in the specific
            provider implementation.
          type: string
          format: uri-reference
        type:
          description: The type of the event.
          type: string
          enum:
            - org.camaraproject.quality-on-demand.v1.qos-status-changed
        specversion:
          description: Version of the specification (CloudEvents 1.0)
          type: string
          enum:
            - '1.0'
        datacontenttype:
          description: media-type of payload
          type: string
          enum:
            - application/json
        data:
          description: Event notification payload
          type: object
        time:
          description: RFC3339 timestamp
          type: string
          format: date-time
    QoDEventQosStatusChanged:
      description: Event to notify a QoS status change
      x-discriminator-value: org.camaraproject.quality-on-demand.v1.qos-status-changed
      allOf:
        - $ref: '#/components/schemas/QoDCloudEvent'
        - type: object
          required:
            - data
          properties:
            data:
              type: object
              description: Event details depending on the event type
              required:
                - sessionId
                - qosStatus
              properties:
                sessionId:
                  $ref: '#/components/schemas/QoDSessionId'
                qosStatus:
                  $ref: '#/components/schemas/QoDEventQosStatus'
                statusInfo:
                  $ref: '#/components/schemas/QoDStatusInfo'
    QoDStatusInfo:
      description: >
        Reason for the new `qosStatus`. Currently `statusInfo` is only
        applicable when `qosStatus` is 'UNAVAILABLE'.

        * `DURATION_EXPIRED` - Session terminated due to requested duration
        expired

        * `NETWORK_TERMINATED` - Network terminated the session before the
        requested duration expired

        * `DELETE_REQUESTED`- User requested the deletion of the session before
        the requested duration expired
      type: string
      enum:
        - DURATION_EXPIRED
        - NETWORK_TERMINATED
        - DELETE_REQUESTED
    QoDDevice:
      description: >
        End-user equipment able to connect to a network. Examples of devices
        include smartphones or IoT sensors/actuators.


        The developer can choose to provide the below specified device
        identifiers:


        * `ipv4Address`

        * `ipv6Address`

        * `phoneNumber`

        * `networkAccessIdentifier`


        NOTE1: the network operator might support only a subset of these
        options. The API consumer can provide multiple identifiers to be
        compatible across different network operators. In this case the
        identifiers MUST belong to the same device.

        NOTE2: as for this Commonalities release, we are enforcing that the
        networkAccessIdentifier is only part of the schema for future-proofing,
        and CAMARA does not currently allow its use. After the CAMARA
        meta-release work is concluded and the relevant issues are resolved, its
        use will need to be explicitly documented in the guidelines.
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/QoDPhoneNumber'
        networkAccessIdentifier:
          $ref: '#/components/schemas/QoDNetworkAccessIdentifier'
        ipv4Address:
          $ref: '#/components/schemas/QoDDeviceIpv4Addr'
        ipv6Address:
          $ref: '#/components/schemas/QoDDeviceIpv6Address'
      minProperties: 1
    QoDDeviceResponse:
      description: >
        An identifier for the end-user equipment able to connect to the network
        that the response refers to. This parameter is only returned when the
        API consumer includes the `device` parameter in their request (i.e. they
        are using a two-legged access token), and is relevant when more than one
        device identifier is specified, as only one of those device identifiers
        is allowed in the response.


        If the API consumer provides more than one device identifier in their
        request, the API provider must return a single identifier which is the
        one they are using to fulfil the request, even if the identifiers do not
        match the same device. API provider does not perform any logic to
        validate/correlate that the indicated device identifiers match the same
        device. No error should be returned if the identifiers are otherwise
        valid to prevent API consumers correlating different identifiers with a
        given end user.
      allOf:
        - $ref: '#/components/schemas/QoDDevice'
        - maxProperties: 1
    QoDApplicationServer:
      description: >
        A server hosting backend applications to deliver some business logic to
        clients.


        The developer can choose to provide the below specified device
        identifiers:


        * `ipv4Address`

        * `ipv6Address`
      type: object
      properties:
        ipv4Address:
          $ref: '#/components/schemas/QoDApplicationServerIpv4Address'
        ipv6Address:
          $ref: '#/components/schemas/QoDApplicationServerIpv6Address'
      minProperties: 1
    QoDNetworkAccessIdentifier:
      description: >-
        A public identifier addressing a subscription in a mobile network. In
        3GPP terminology, it corresponds to the GPSI formatted with the External
        Identifier ({Local Identifier}@{Domain Identifier}). Unlike the
        telephone number, the network access identifier is not subjected to
        portability ruling in force, and is individually managed by each
        operator.
      type: string
      example: 123456789@domain.com
    QoDPhoneNumber:
      description: >-
        A public identifier addressing a telephone subscription. In mobile
        networks it corresponds to the MSISDN (Mobile Station International
        Subscriber Directory Number). In order to be globally unique it has to
        be formatted in international format, according to E.164 standard,
        prefixed with '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: '+123456789'
    QoDDeviceIpv4Addr:
      type: object
      description: >
        The device should be identified by either the public (observed) IP
        address and port as seen by the application server, or the private
        (local) and any public (observed) IP addresses in use by the device
        (this information can be obtained by various means, for example from
        some DNS servers).


        If the allocated and observed IP addresses are the same (i.e. NAT is not
        in use) then  the same address should be specified for both
        publicAddress and privateAddress.


        If NAT64 is in use, the device should be identified by its publicAddress
        and publicPort, or separately by its allocated IPv6 address (field
        ipv6Address of the Device object)


        In all cases, publicAddress must be specified, along with at least one
        of either privateAddress or publicPort, dependent upon which is known.
        In general, mobile devices cannot be identified by their public IPv4
        address alone.
      properties:
        publicAddress:
          $ref: '#/components/schemas/QoDSingleIpv4Addr'
        privateAddress:
          $ref: '#/components/schemas/QoDSingleIpv4Addr'
        publicPort:
          $ref: '#/components/schemas/QoDPort'
      anyOf:
        - required:
            - publicAddress
            - privateAddress
        - required:
            - publicAddress
            - publicPort
      example:
        publicAddress: 203.0.113.0
        publicPort: 59765
    QoDSingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: 203.0.113.0
    QoDDeviceIpv6Address:
      description: >
        The device should be identified by the observed IPv6 address, or by any
        single IPv6 address from within the subnet allocated to the device (e.g.
        adding ::0 to the /64 prefix).


        The session shall apply to all IP flows between the device subnet and
        the specified application server, unless further restricted by the
        optional parameters devicePorts or applicationServerPorts.
      type: string
      format: ipv6
      example: '2001:db8:85a3:8d3:1319:8a2e:370:7344'
    QoDApplicationServerIpv4Address:
      type: string
      example: 198.51.100.0/24
      description: |
        IPv4 address may be specified in form <address/mask> as:
          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.
    QoDApplicationServerIpv6Address:
      type: string
      example: '2001:db8:85a3:8d3:1319:8a2e:370:7344'
      description: |
        IPv6 address may be specified in form <address/mask> as:
          - address - The /128 subnet is optional for single addresses:
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
          - address/mask - an IP v6 number with a mask:
            - 2001:db8:85a3:8d3::0/64
            - 2001:db8:85a3:8d3::/64
    QoDQosStatus:
      description: >
        The current status of the requested QoS session. The status can be one
        of the following:

        * `REQUESTED` - QoS has been requested by creating a session

        * `AVAILABLE` - The requested QoS has been provided by the network

        * `UNAVAILABLE` - The requested QoS cannot be provided by the network
        due to some reason
      type: string
      enum:
        - REQUESTED
        - AVAILABLE
        - UNAVAILABLE
    QoDEventQosStatus:
      description: >
        The current status of a requested or previously available session.
        Applicable values in the event are:

        *  `AVAILABLE` - The requested QoS has been provided by the network.

        *  `UNAVAILABLE` - A requested or previously available QoS session is
        now unavailable. `statusInfo` may provide additional information about
        the reason for the unavailability.
      type: string
      enum:
        - AVAILABLE
        - UNAVAILABLE
    QoDRetrieveSessionsInput:
      description: Parameters to get QoS session information by device
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          $ref: '#/components/schemas/QoDPhoneNumber'
        device:
          $ref: '#/components/schemas/QoDDevice'
    QoDRetrieveSessionsOutput:
      description: QoS session information for a given device
      type: object
      properties:
        sessions:
          description: >-
            An array of QoS sessions for the given device. The array is empty if
            no sessions are found.
          type: array
          items:
            $ref: '#/components/schemas/QoDSessionInfo'
          minItems: 0
    QoDApiError:
      required:
        - code
        - details
        - ref
        - title
      type: object
      properties:
        code:
          type: string
          description: code of the error
        title:
          type: string
          description: title of the error
        ref:
          type: string
          description: ref of the error
        details:
          type: string
          description: details of the error
  responses:
    ConsentsGeneric400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsentsApiError'
    ConsentsGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsentsApiError'
    ConsentsGeneric403:
      description: |
        Client does not have sufficient permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsentsApiError'
    ConsentsGeneric500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsentsApiError'
    ConsentsGeneric503:
      description: Service unavailable. Typically the server is down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsentsApiError'
    ConsentsGeneric504:
      description: >-
        Request time exceeded. If it happens repeatedly, consider reducing the
        request complexity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsentsApiError'
    NumberVerificationGeneric400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric403:
      description: |
        Client does not have sufficient permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric503:
      description: Service unavailable. Typically the server is down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    NumberVerificationGeneric504:
      description: >-
        Request time exceeded. If it happens repeatedly, consider reducing the
        request complexity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumberVerificationApiError'
    SimSwapGeneric400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric422:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric503:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    SimSwapGeneric504:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimSwapApiError'
    OperativeGeneric400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric403:
      description: |
        Client does not have sufficient permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric404:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric409:
      description: Conflict - Resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric503:
      description: Service unavailable. Typically the server is down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    OperativeGeneric504:
      description: >-
        Request time exceeded. If it happens repeatedly, consider reducing the
        request complexity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperativeApiError'
    CatalogBadRequest:
      description: Bad request - Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogError'
    CatalogNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogError'
    CatalogInternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogError'
    TenantCatalogInternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TenantCatalogError'
    ProductOrderCatalogBadRequest:
      description: Bad request - Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductOrderCatalogError'
    ProductOrderCatalogNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductOrderCatalogError'
    ProductOrderCatalogInternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductOrderCatalogError'
    QoSProfilesGeneric400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoSProfilesApiError'
    QoSProfilesGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoSProfilesApiError'
    QoSProfilesGeneric403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoSProfilesApiError'
    QoSProfilesGeneric404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoSProfilesApiError'
    QoSProfilesGeneric422:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoSProfilesApiError'
    QoSProfilesGeneric429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoSProfilesApiError'
    QoDGeneric400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric410:
      description: Gone
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric422:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
    QoDGeneric429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QoDApiError'
  examples:
    QoSProfilesLIST_OF_QOS_PROFILES:
      summary: A list of QoS profiles with a single entry
      description: Example response when requesting a list of QoS profiles
      value:
        profiles:
          - name: voice
            description: QoS profile for high-quality interactive voice
            status: ACTIVE
            targetMinUpstreamRate:
              value: 100
              unit: kbps
            targetMinDownstreamRate:
              value: 100
              unit: kbps
            minDuration:
              value: 1
              unit: Days
            maxDuration:
              value: 10
              unit: Days
            priority: 10
            packetDelayBudget:
              value: 50
              unit: Milliseconds
            jitter:
              value: 5
              unit: Milliseconds
            packetErrorLossRate: 3
            l4sQueueType: non-l4s-queue
    QoDSESSION_CREATION_EXAMPLE:
      summary: Successful session creation with device not included in response
      description: >-
        Example response after a new QoS session has been created using a
        3-legged access token, or possibly a single device identifier
      value:
        applicationServer:
          ipv4Address: 198.51.100.0/24
        qosProfile: QOS_L
        sink: 'https://application-server.com/notifications'
        sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        duration: 3600
        qosStatus: REQUESTED
    QoDSESSION_CREATION_EXAMPLE_WITH_DEVICE_RESPONSE:
      summary: Successful session creation with device included in response
      description: >-
        Example response after a new QoS session has been created using a
        2-legged access token with multiple device identifiers, or possibly only
        a single device identifier
      value:
        device:
          phoneNumber: '+123456789'
        applicationServer:
          ipv4Address: 198.51.100.0/24
        qosProfile: QOS_L
        sink: 'https://application-server.com/notifications'
        sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        duration: 3600
        qosStatus: REQUESTED
    QoDSESSION_AVAILABLE_EXAMPLE:
      summary: QoS session status is available
      description: QoS session info when status is available
      value:
        duration: 3600
        applicationServer:
          ipv4Address: 198.51.100.0/24
        qosProfile: QOS_L
        sink: 'https://application-server.com/notifications'
        sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        startedAt: '2024-06-01T12:00:00Z'
        expiresAt: '2024-06-01T13:00:00Z'
        qosStatus: AVAILABLE
    QoDSESSION_UNAVAILABLE_EXAMPLE:
      summary: QoS session is unavailable
      description: QoS session info when status is unavailable due to network termination
      value:
        duration: 2428
        applicationServer:
          ipv4Address: 198.51.100.0/24
        qosProfile: QOS_L
        sink: 'https://application-server.com/notifications'
        sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        startedAt: '2024-06-01T12:00:00Z'
        expiresAt: '2024-06-01T12:40:28Z'
        qosStatus: UNAVAILABLE
        statusInfo: NETWORK_TERMINATED
    QoDQOS_STATUS_CHANGED_EXAMPLE:
      summary: QoS status changed
      description: >-
        Cloud event example for QoS status change to UNAVAILABLE due to
        DURATION_EXPIRED
      value:
        id: 83a0d986-0866-4f38-b8c0-fc65bfcda452
        source: >-
          https://api.example.com/qod/v1/sessions/123e4567-e89b-12d3-a456-426614174000
        specversion: '1.0'
        type: org.camaraproject.quality-on-demand.v1.qos-status-changed
        time: '2024-06-01T13:00:00Z'
        data:
          sessionId: 123e4567-e89b-12d3-a456-426614174000
          qosStatus: UNAVAILABLE
          statusInfo: DURATION_EXPIRED
    QoDRETRIEVE_SESSIONS_EXAMPLE:
      summary: List of QoS sessions for the specified device
      description: A single QoS session for the specified device is available
      value:
        sessions:
          - applicationServer:
              ipv4Address: 0.0.0.0/0
            qosProfile: QOS_L
            sink: 'https://application-server.com/notifications'
            sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            duration: 3600
            startedAt: '2024-06-01T12:00:00Z'
            expiresAt: '2024-06-01T13:00:00Z'
            qosStatus: AVAILABLE
    QoDRETRIEVE_SESSIONS_EXAMPLE_WITH_DEVICE_RESPONSE:
      summary: >-
        List of QoS sessions for a specified device with the device in the
        response
      description: >-
        A single QoS session for the device is available and the device to which
        the session applies is included in the response
      value:
        sessions:
          - device:
              phoneNumber: '+123456789'
            applicationServer:
              ipv4Address: 0.0.0.0/0
            qosProfile: QOS_L
            sink: 'https://application-server.com/notifications'
            sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            duration: 3600
            startedAt: '2024-06-01T12:00:00Z'
            expiresAt: '2024-06-01T13:00:00Z'
            qosStatus: AVAILABLE
    QoDRETRIEVE_SESSIONS_EMPTY_EXAMPLE:
      summary: No sessions found for the device
      description: An empty array is returned when no sessions are found for the device
      value:
        sessions: []
  parameters:
    QoDx-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/QoDXCorrelator'
  headers:
    QoDx-correlator:
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/QoDXCorrelator'
