openapi: 3.2.0
info:
  title: Pagopa Attributes 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 attributes 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: Attributes
  description: Attributes routes
paths:
  /certifiedAttributes:
    get:
      tags:
      - Attributes
      summary: List Certified Attributes
      description: Retrieve a list of Certified Attributes
      operationId: getCertifiedAttributes
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Certified Attributes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertifiedAttributes'
          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:
      - Attributes
      summary: Create a certified Attribute
      description: 'Create a certified Attribute

        The Attribute must

        - have a unique name across all Attributes in the Platform

        - have a unique code across certified Attributes owned by the requester'
      operationId: createCertifiedAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertifiedAttributeSeed'
      responses:
        '201':
          description: Certified Attribute created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertifiedAttribute'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /certifiedAttributes/{attributeId}:
    parameters:
    - name: attributeId
      in: path
      description: The ID of the Attribute to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/AttributeId'
    get:
      tags:
      - Attributes
      summary: Retrieve a certified Attribute
      operationId: getCertifiedAttribute
      responses:
        '200':
          description: Certified attribute retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertifiedAttribute'
          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: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /declaredAttributes/{attributeId}:
    parameters:
    - name: attributeId
      in: path
      description: The ID of the Attribute to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/AttributeId'
    get:
      tags:
      - Attributes
      summary: Retrieve a declared Attribute
      operationId: getDeclaredAttribute
      responses:
        '200':
          description: Declared attribute retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredAttribute'
          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: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /verifiedAttributes/{attributeId}:
    parameters:
    - name: attributeId
      in: path
      description: The ID of the Attribute to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/AttributeId'
    get:
      tags:
      - Attributes
      summary: Retrieve a verified Attribute
      operationId: getVerifiedAttribute
      responses:
        '200':
          description: Verified attribute retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedAttribute'
          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: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /verifiedAttributes:
    get:
      tags:
      - Attributes
      summary: List Verified Attributes
      description: Retrieve a list of Verified Attributes
      operationId: getVerifiedAttributes
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Verified Attributes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedAttributes'
          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:
      - Attributes
      summary: Create a verified Attribute
      description: 'Create a verified Attribute

        The Attribute must have a unique name across all Attributes in the Platform'
      operationId: createVerifiedAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifiedAttributeSeed'
      responses:
        '201':
          description: Verified Attribute created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedAttribute'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
  /declaredAttributes:
    get:
      tags:
      - Attributes
      summary: List Declared Attributes
      description: Retrieve a list of Declared Attributes
      operationId: getDeclaredAttributes
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Declared Attributes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredAttributes'
          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:
      - Attributes
      summary: Create a declared Attribute
      description: 'Create a declared Attribute

        The Attribute must have a unique name across all Attributes in the Platform'
      operationId: createDeclaredAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclaredAttributeSeed'
      responses:
        '201':
          description: Declared Attribute created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredAttribute'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - DPoPAuth: []
        DPoPProofHeader: []
    servers:
    - url: https://api.interop.pagopa.it/v3
      description: Production environment
components:
  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

        '
  schemas:
    DeclaredAttribute:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - description
      - createdAt
    CertifiedAttributes:
      type: object
      additionalProperties: false
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CertifiedAttribute'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    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
    DeclaredAttributeSeed:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 100
        description:
          type: string
          minLength: 10
          maxLength: 500
      required:
      - description
      - name
    VerifiedAttribute:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - description
      - createdAt
    AttributeId:
      type: string
      format: uuid
      description: The unique identifier of the Attribute
    DeclaredAttributes:
      type: object
      additionalProperties: false
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/DeclaredAttribute'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    CertifiedAttributeSeed:
      type: object
      additionalProperties: false
      description: Models the attribute registry entry as payload response
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 500
        description:
          type: string
          minLength: 1
          maxLength: 500
        code:
          type: string
          minLength: 1
          maxLength: 64
          description: The identifier of the attribute on the source registry
      required:
      - description
      - name
      - code
    VerifiedAttributes:
      type: object
      additionalProperties: false
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/VerifiedAttribute'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - results
      - pagination
    CertifiedAttribute:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          description: The identifier of the attribute on the source registry
        description:
          type: string
        origin:
          type: string
          description: Identifier of the origin of this attribute, e.g. "IPA"
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - description
      - code
      - origin
      - createdAt
    VerifiedAttributeSeed:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 100
        description:
          type: string
          minLength: 10
          maxLength: 500
      required:
      - description
      - name
    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
  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
    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