openapi: 3.2.0
info:
  title: Pagopa Clients API
  contact:
    name: API Support
    url: https://github.com/pagopa/pdnd-interop-frontend/issues
  termsOfService: https://selfcare.interop.pagopa.it/ui/it/termini-di-servizio
  x-summary: PDND Interoperability API
  version: '1.0'
  description: 'Operations tagged clients across 3 of this provider''s published API definitions: interop-api-v3.yaml, pagopa-pdnd-interop-v2-openapi.yml, pagopa-pdnd-interop-v3-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.interop.pagopa.it/v3
  description: Production environment
- url: https://api.interop.pagopa.it/v2
  description: PROD environment
tags:
- name: Clients
  description: Clients routes
paths:
  /clients:
    get:
      tags:
      - Clients
      summary: List Clients
      description: Retrieve a list of Clients based on filters
      operationId: getClients
      parameters:
      - in: query
        name: name
        description: 'Filter Clients by name.

          If not specified, return Clients with any name.

          If specified, since client name is visible only to the owner (consumer),

          the response will include only Clients owned by the requester.

          '
        schema:
          type: string
      - name: consumerId
        in: query
        description: 'Filter Clients by Consumer ID (Client owner).

          If not specified, return Clients for any Consumer.

          '
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Clients retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Clients'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    post:
      tags:
      - Clients
      summary: Create a new consumer client
      description: Create a new consumer client for the requester's organization.
      operationId: createClient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientSeed'
      responses:
        '200':
          description: Consumer client created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}:
    parameters:
    - name: clientId
      in: path
      description: The ID of the Client to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    get:
      tags:
      - Clients
      summary: Retrieve a Client
      description: Retrieve a Client by its ID
      operationId: getClient
      responses:
        '200':
          description: Client retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    delete:
      tags:
      - Clients
      summary: Delete a Consumer Client
      description: Delete a Consumer Client by its ID
      operationId: deleteClient
      responses:
        '200':
          description: Consumer client deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidObject'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}/purposes:
    parameters:
    - name: clientId
      in: path
      description: The ID of the Client
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    get:
      tags:
      - Clients
      summary: List Purposes linked to a Client
      description: Retrieve a list of Purposes linked to a specific Client
      operationId: getClientPurposes
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/EserviceIdsParam'
      - in: query
        name: states
        description: 'Filter Purposes by states. If not specified, return Purposes for any state. If "ARCHIVED" is included in the filter, only Purposes where all their versions are in the "ARCHIVED" state will be returned, excluding those that have versions in other states.

          '
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PurposeVersionState'
          default: []
        explode: false
        required: false
      responses:
        '200':
          description: List of Purposes linked to the Client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purposes'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    post:
      tags:
      - Clients
      summary: Link a Client to a Purpose
      description: 'Link a Client to a Purpose

        The Purpose must be in Active or Suspended state'
      operationId: addClientPurpose
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientAddPurpose'
        required: true
      responses:
        '200':
          description: Client linked to the Purpose
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidObject'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}/purposes/{purposeId}:
    parameters:
    - name: clientId
      in: path
      description: The ID of the Client to unlink the Purpose from
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    - name: purposeId
      in: path
      description: The ID of the Purpose to unlink from the Client
      required: true
      schema:
        $ref: '#/components/schemas/PurposeId'
    delete:
      tags:
      - Clients
      summary: Unlink a Client from a Purpose
      description: Unlink a Client from a Purpose, removing the association between them
      operationId: removeClientPurpose
      responses:
        '200':
          description: Client unlinked from the Purpose
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidObject'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}/keys:
    parameters:
    - name: clientId
      in: path
      description: The ID of the Client
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    get:
      tags:
      - Clients
      summary: List Client Keys
      description: Retrieve a list of keys associated with a Client
      operationId: getClientKeys
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: List of Client Keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKs'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    post:
      tags:
      - Clients
      summary: Create a new Client Key for a specific Client
      description: Create a new client key associated with a Client
      operationId: createClientKey
      requestBody:
        description: Client Key to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeySeed'
      responses:
        '200':
          description: Client Key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}/keys/{keyId}:
    parameters:
    - name: clientId
      in: path
      description: ID of the client to look up
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    - name: keyId
      in: path
      description: the unique identifier of the key (kid) to lookup
      required: true
      schema:
        type: string
    delete:
      tags:
      - Clients
      summary: Deletes a key by client and key identifier (kid)
      description: Given a client and key identifiers it deletes the corresponding key, if any
      operationId: deleteClientKeyById
      responses:
        '200':
          description: the corresponding key has been deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidObject'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}/users:
    parameters:
    - name: clientId
      in: path
      description: ID of Client the users belong to
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    get:
      tags:
      - Clients
      summary: List Client Users
      description: Retrieve a list of Users associated with a Client
      operationId: getClientUsers
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      responses:
        '200':
          description: Client Users retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    post:
      tags:
      - Clients
      summary: Link a User to a Client
      description: 'Link a security User to a Client.

        This allows the specified User to manage or use credentials stored in the Client.

        The requester organization must be the owner of the Client.

        Additionally, the User being added must not already be associated with the Client.'
      operationId: addClientUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkUser'
        required: true
      responses:
        '200':
          description: User linked to the Client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidObject'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /clients/{clientId}/users/{userId}:
    parameters:
    - name: clientId
      in: path
      description: The Client id
      required: true
      schema:
        $ref: '#/components/schemas/ClientId'
    - name: userId
      in: path
      description: The ID of the User to unlink from the Client
      required: true
      schema:
        type: string
        format: uuid
    delete:
      summary: Unlink a User from a Client
      description: Unlink a User from a Client.
      operationId: removeClientUser
      tags:
      - Clients
      responses:
        '200':
          description: User unlinked from Client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidObject'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/RateLimitLimitHeader'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/RateLimitRemainingHeader'
            X-Rate-Limit-Interval:
              $ref: '#/components/headers/RateLimitIntervalHeader'
            Digest:
              $ref: '#/components/headers/IntegrityRest02DigestHeader'
            Agid-JWT-Signature:
              $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
components:
  schemas:
    PurposeTemplateId:
      type: string
      format: uuid
      description: The unique identifier of the Purpose Template
    FullClient:
      type: object
      description: Models a Client with unrestricted field visibility
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        consumerId:
          description: Tenant ID of the Client owner
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - consumerId
      - name
      - createdAt
    JWK:
      description: JSON Web Key
      type: object
      additionalProperties: false
      properties:
        kty:
          type: string
        key_ops:
          type: array
          items:
            type: string
        use:
          type: string
        alg:
          type: string
        kid:
          $ref: '#/components/schemas/Kid'
        x5u:
          type: string
          minLength: 1
        x5t:
          type: string
        x5t#S256:
          type: string
        x5c:
          type: array
          items:
            type: string
        crv:
          type: string
        x:
          type: string
        y:
          type: string
        d:
          type: string
        k:
          type: string
        n:
          type: string
        e:
          type: string
        p:
          type: string
        q:
          type: string
        dp:
          type: string
        dq:
          type: string
        qi:
          type: string
        oth:
          uniqueItems: false
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OtherPrimeInfo'
      required:
      - kty
      - kid
    Problem:
      properties:
        type:
          description: URI reference of type definition
          type: string
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem
          example: 503
          format: int32
          minimum: 100
          type: integer
          exclusiveMaximum: 600
        title:
          description: A short, summary of the problem type. Written in english and readable
          example: Service Unavailable
          maxLength: 64
          pattern: ^[ -~]{0,64}$
          type: string
        correlationId:
          description: Unique identifier of the request
          example: 53af4f2d-0c87-41ef-a645-b726a821852b
          maxLength: 64
          type: string
        detail:
          description: A human readable explanation of the problem
          example: Request took too long to complete
          maxLength: 4096
          pattern: ^.{0,1024}$
          type: string
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ProblemError'
      additionalProperties: false
      required:
      - type
      - status
      - title
    ProblemError:
      properties:
        code:
          description: Internal code of the error
          example: 123-4567
          minLength: 8
          maxLength: 8
          pattern: ^[0-9]{3}-[0-9]{4}$
          type: string
        detail:
          description: A human readable explanation specific to this occurrence of the problem
          example: Parameter not valid
          maxLength: 4096
          pattern: ^.{0,1024}$
          type: string
      required:
      - code
      - detail
    PurposeId:
      type: string
      format: uuid
      description: The unique identifier of the Purpose
    Client:
      description: 'Models a Client with field visibility based on the requester''s permissions.

        Only the Client owner has access to all fields.

        '
      oneOf:
      - $ref: '#/components/schemas/FullClient'
      - $ref: '#/components/schemas/PartialClient'
    Clients:
      type: object
      additionalProperties: false
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Client'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    ClientAddPurpose:
      type: object
      additionalProperties: false
      properties:
        purposeId:
          $ref: '#/components/schemas/PurposeId'
      required:
      - purposeId
    ClientSeed:
      description: Client creation request body
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 5
          maxLength: 60
        description:
          type: string
          minLength: 10
          maxLength: 250
        members:
          type: array
          items:
            type: string
            format: uuid
      required:
      - name
      - members
    LinkUser:
      type: object
      additionalProperties: false
      properties:
        userId:
          type: string
          format: uuid
      required:
      - userId
    Kid:
      type: string
      description: The unique identifier of the Key
    PurposeVersionState:
      type: string
      description: Purpose State
      enum:
      - ACTIVE
      - DRAFT
      - SUSPENDED
      - WAITING_FOR_APPROVAL
      - ARCHIVED
      - REJECTED
    KeyUse:
      type: string
      description: Represents the Use field of key
      enum:
      - SIG
      - ENC
    PartialClient:
      type: object
      description: Models a Client with restricted field visibility
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        consumerId:
          description: Tenant ID of the Client owner
          type: string
          format: uuid
      required:
      - id
      - consumerId
    KeySeed:
      description: Models the seed for a public key to be persisted
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          description: Base64 UTF-8 encoding of a public key in PEM format
        use:
          $ref: '#/components/schemas/KeyUse'
        alg:
          type: string
          description: The algorithm type of the key.
        name:
          type: string
          description: Name given to the current key.
          minLength: 5
          maxLength: 60
      required:
      - key
      - use
      - alg
      - name
    ClientId:
      type: string
      format: uuid
      description: The unique identifier of the Client
    JWKs:
      type: object
      additionalProperties: false
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/JWK'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    VoidObject:
      type: object
      additionalProperties: false
      description: An empty object
    DelegationId:
      type: string
      format: uuid
      description: The unique identifier of the Delegation
    EServiceId:
      type: string
      format: uuid
      description: The unique identifier of the E-Service
    PurposeVersion:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        state:
          $ref: '#/components/schemas/PurposeVersionState'
        createdAt:
          type: string
          format: date-time
        suspendedAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        firstActivationAt:
          type: string
          format: date-time
        dailyCalls:
          description: Maximum number of daily calls performed using this version
          type: integer
          format: int32
          minimum: 1
          maximum: 1000000000
        rejectionReason:
          type: string
      required:
      - id
      - state
      - dailyCalls
      - createdAt
      description: business representation of a purpose version
    Purposes:
      type: object
      additionalProperties: false
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Purpose'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    Users:
      type: object
      additionalProperties: false
      description: Paginated list of users
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    OtherPrimeInfo:
      type: object
      additionalProperties: false
      properties:
        r:
          type: string
        d:
          type: string
        t:
          type: string
      required:
      - r
      - d
      - t
    Purpose:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        eserviceId:
          $ref: '#/components/schemas/EServiceId'
        consumerId:
          type: string
          format: uuid
        suspendedByConsumer:
          type: boolean
        suspendedByProducer:
          type: boolean
        title:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isFreeOfCharge:
          type: boolean
        freeOfChargeReason:
          type: string
        delegationId:
          $ref: '#/components/schemas/DelegationId'
        currentVersion:
          $ref: '#/components/schemas/PurposeVersion'
        waitingForApprovalVersion:
          $ref: '#/components/schemas/PurposeVersion'
        rejectedVersion:
          $ref: '#/components/schemas/PurposeVersion'
        purposeTemplateId:
          $ref: '#/components/schemas/PurposeTemplateId'
      required:
      - id
      - eserviceId
      - consumerId
      - title
      - description
      - createdAt
      - isFreeOfCharge
    User:
      type: object
      additionalProperties: false
      description: User information
      properties:
        userId:
          type: string
          format: uuid
          description: User identifier
        name:
          type: string
          description: User first name
        familyName:
          type: string
          description: User last name
        roles:
          type: array
          items:
            type: string
          description: User roles
      required:
      - userId
      - name
      - familyName
      - roles
    Pagination:
      type: object
      additionalProperties: false
      properties:
        offset:
          type: integer
          format: int32
          minimum: 0
        limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 50
        totalCount:
          type: integer
          format: int32
          minimum: 0
      required:
      - offset
      - limit
      - totalCount
    Key:
      description: Key
      type: object
      additionalProperties: false
      properties:
        clientId:
          $ref: '#/components/schemas/ClientId'
        jwk:
          $ref: '#/components/schemas/JWK'
      required:
      - clientId
      - jwk
    JWK_2:
      description: JSON Web Key
      type: object
      additionalProperties: false
      properties:
        kty:
          type: string
        key_ops:
          type: array
          items:
            type: string
        use:
          type: string
        alg:
          type: string
        kid:
          type: string
        x5u:
          type: string
          minLength: 1
        x5t:
          type: string
        x5t#S256:
          type: string
        x5c:
          type: array
          items:
            type: string
        crv:
          type: string
        x:
          type: string
        y:
          type: string
        d:
          type: string
        k:
          type: string
        n:
          type: string
        e:
          type: string
        p:
          type: string
        q:
          type: string
        dp:
          type: string
        dq:
          type: string
        qi:
          type: string
        oth:
          uniqueItems: false
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OtherPrimeInfo'
      required:
      - kty
      - kid
    Purpose_2:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        eserviceId:
          type: string
          format: uuid
        consumerId:
          type: string
          format: uuid
        suspendedByConsumer:
          type: boolean
        suspendedByProducer:
          type: boolean
        title:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isRiskAnalysisValid:
          type: boolean
        isFreeOfCharge:
          type: boolean
        freeOfChargeReason:
          type: string
        delegationId:
          type: string
          format: uuid
        currentVersion:
          $ref: '#/components/schemas/PurposeVersion'
        waitingForApprovalVersion:
          $ref: '#/components/schemas/PurposeVersion'
        rejectedVersion:
          $ref: '#/components/schemas/PurposeVersion'
        purposeTemplateId:
          type: string
          format: uuid
      required:
      - id
      - eserviceId
      - consumerId
      - title
      - description
      - createdAt
      - isRiskAnalysisValid
      - isFreeOfCharge
    ClientAddPurpose_2:
      type: object
      additionalProperties: false
      properties:
        purposeId:
          type: string
          format: uuid
      required:
      - purposeId
  headers:
    IntegrityRest02AgidJwtSignatureHeader:
      description: 'The `Agid-JWT-Signature` header contains a JSON Web Signature (JWS) signed with the PDND API private key.

        It ensures payload integrity and non-repudiation across all responses (both success and error), in compliance with: 1) Linee Guida sull''interoperabilità tecnica delle Pubbliche Amministrazioni - Pattern di sicurezza,  2) RFC 7515 and 3) RFC 7519.

        '
      schema:
        type: string
    RateLimitRemainingHeader:
      schema:
        type: integer
        format: int32
        minimum: 0
      description: Remaining requests within time interval
    RateLimitIntervalHeader:
      schema:
        type: integer
        format: int32
        minimum: 0
      description: Time interval in milliseconds. Allowed requests will be constantly replenished during the interval. At the end of the interval the max allowed requests will be available
    RateLimitLimitHeader:
      schema:
        type: integer
        format: int32
        minimum: 0
      description: Max allowed requests within time interval
    IntegrityRest02DigestHeader:
      schema:
        type: string
        pattern: ^SHA-256=[a-zA-Z0-9+/]{43}=$
      description: 'Digest of the body using the canonical JSON representation of the response body.

        The digest is calculated using the SHA-256 algorithm on the response body

        exactly as it is sent to the client, encoded in Base64 as per RFC 3230

        '
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/RateLimitLimitHeader'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/RateLimitRemainingHeader'
        X-Rate-Limit-Interval:
          $ref: '#/components/headers/RateLimitIntervalHeader'
        Digest:
          $ref: '#/components/headers/IntegrityRest02DigestHeader'
        Agid-JWT-Signature:
          $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
    Conflict:
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/RateLimitLimitHeader'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/RateLimitRemainingHeader'
        X-Rate-Limit-Interval:
          $ref: '#/components/headers/RateLimitIntervalHeader'
        Digest:
          $ref: '#/components/headers/IntegrityRest02DigestHeader'
        Agid-JWT-Signature:
          $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/RateLimitLimitHeader'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/RateLimitRemainingHeader'
        X-Rate-Limit-Interval:
          $ref: '#/components/headers/RateLimitIntervalHeader'
        Digest:
          $ref: '#/components/headers/IntegrityRest02DigestHeader'
        Agid-JWT-Signature:
          $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/RateLimitLimitHeader'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/RateLimitRemainingHeader'
        X-Rate-Limit-Interval:
          $ref: '#/components/headers/RateLimitIntervalHeader'
        Digest:
          $ref: '#/components/headers/IntegrityRest02DigestHeader'
        Agid-JWT-Signature:
          $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/RateLimitLimitHeader'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/RateLimitRemainingHeader'
        X-Rate-Limit-Interval:
          $ref: '#/components/headers/RateLimitIntervalHeader'
        Digest:
          $ref: '#/components/headers/IntegrityRest02DigestHeader'
        Agid-JWT-Signature:
          $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
    TooManyRequests:
      description: Too Many Requests
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/RateLimitLimitHeader'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/RateLimitRemainingHeader'
        X-Rate-Limit-Interval:
          $ref: '#/components/headers/RateLimitIntervalHeader'
        Digest:
          $ref: '#/components/headers/IntegrityRest02DigestHeader'
        Agid-JWT-Signature:
          $ref: '#/components/headers/IntegrityRest02AgidJwtSignatureHeader'
  parameters:
    LimitParam:
      in: query
      name: limit
      description: Maximum number of results to return
      required: true
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 50
    EserviceIdsParam:
      in: query
      name: eserviceIds
      description: Filter by E-Service IDs. If not specified, return results for any E-Service
      required: false
      explode: false
      schema:
        type: array
        items:
          type: string
          format: uuid
        default: []
    OffsetParam:
      in: query
      name: offset
      description: Pagination starting position
      required: true
      schema:
        type: integer
        format: int32
        minimum: 0
  securitySchemes:
    DPoPAuth:
      type: http
      scheme: DPoP
      description: 'This Authorization header must be used alongside the DPoP Proof JWT.

        Use:

        Authorization: DPoP <access_token>


        The access token generated must also have a cnf field.

        '
    DPoPProofHeader:
      type: apiKey
      in: header
      name: DPoP
      description: 'DPoP proof JWT for sender-constrained access. Must accompany the DPoP Authorization header.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- interop-api-v3.yaml
- pagopa-pdnd-interop-v2-openapi.yml
- pagopa-pdnd-interop-v3-openapi.yml