KPN Parties API

openapi: 3.2.0
info:
  title: FIAM-KPN Parties API
  description: A collection of crates for federated identity and access management
  license:
    name: ''
  version: 0.1.1
servers:
- url: https://api-prd.kpn.com/fiam
  description: Server
tags:
- name: Parties
  description: Party and participant management endpoints
paths:
  /api/v1/dataspaces:
    get:
      tags:
      - Parties
      operationId: get_dataspaces
      responses:
        '200':
          description: Dataspaces details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataspaceInfo'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Dataspaces not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
  /api/v1/parties:
    get:
      tags:
      - Parties
      operationId: search_parties
      parameters:
      - name: active_only
        in: query
        description: Optional parameter used to search by party's \"Active\" status.
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: name
        in: query
        description: Optional parameter used to search by party's name. Can contain a single * as wildcard.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: eori
        in: query
        description: 'Optional parameter used to search by party''s EORI. Can contain a single * as wildcard. It searches through the

          party_id array  for matching eori (contained in the party_id array). This parameter must be considered

          deprecated and will be removed in future  releases.'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: party_id
        in: query
        description: 'Optional parameter used to search by party''s ID. Can contain a single * as wildcard. It searches through the

          party_id array  for matching party_id.'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: certified_only
        in: query
        description: Search for parties that play one of the certified roles as defined in iSHARE role framework.
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: date_time
        in: query
        description: Search parties with a specific adherence date
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: adherenceStatus
        in: query
        description: Search for parties with adherence status like \"Active\", \"Revoked\",\"Not Active\", \"Pending\"
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: adherenceStartdate
        in: query
        description: Search parties with a specific adherence start date
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: adherenceEnddate
        in: query
        description: Search parties with a specific adherence end date
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: registrarPartyId
        in: query
        description: Search parties by their registrar Participant Registry's ID number
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: webSiteUrl
        in: query
        description: Search a party by their website URL
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: companyEmail
        in: query
        description: Search a party by their email ID
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: companyPhone
        in: query
        description: Search a party by their company phone number
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
      - name: publiclyPublishable
        in: query
        description: Search parties whose general company contact information is allowed to be published
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: tags
        in: query
        description: 'Search parties who match any of the keywords that they have added in their participant information under tags.

          It is a free text field and can contain any value'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: framework
        in: query
        description: 'Search parties based on which framework they were onboarded with. Currently parties can only be registered with

          \"iSHARE\" framework'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: subjectName
        in: query
        description: 'Search parties based on the subject name of their PKI (x509) certificates. Usually to find a party who is

          requesting tokens'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: role
        in: query
        description: 'Search parties based on their roles as defined in the iSHARE role framework. Possible roles are ServiceConsumer,

          ServiceProvider,  EntitledParty, AuthorisationRegistry, IdentityProvider,  IdentityBroker and IdentityBroker

          and ParticipantRegistry,  iShareSatellite (deprecated, will be removed in future releases,  use

          ParticipantRegistry instead).'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: loA
        in: query
        description: 'Search parties based on their level of assurance which is registered in the participant list. Possible values

          are Low/Substantial/High'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: compliancyVerified
        in: query
        description: Search parties that have their compliance to framework verified or not.
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: legalAdherence
        in: query
        description: 'Search parties that have signed the appropriate legal agreements and that have been verified during or after

          onboarding. Parties adhering to legal agreements are legally obliged to adhere to terms of use of data.'
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: authorizationRegistryID
        in: query
        description: 'Search parties based on their authorization registry provider. The ID of the authorization registry must be

          provided in search parameter, and this must be listed as the authorization registry in the participant record'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: authorizationRegistryName
        in: query
        description: 'Search parties based on their authorization registry provider. The name of the authorization registry must be

          provided in search parameter and this must be listed as authorization registry in the participant record'
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: dataSpaceID
        in: query
        description: Search parties based on data-spaces they participate in. The ID of the data-space must be provided
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: dataSpaceTitle
        in: query
        description: Search parties based on data-spaces they participate in. The name of the data-space must be provided
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: countriesOfOperation
        in: query
        description: Search parties by name of country they list as their country of operation
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: sectorIndustry
        in: query
        description: Search parties by name of sector they list as their sector/industry
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: page
        in: query
        description: 'The parties API by default uses pagination. Each page size is fixed at 10 parties per page. When search results

          into more then 10 parties, the page parameter must be added for next pages'
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
      - name: size
        in: query
        description: into more then 10 parties, the page parameter must be added for next pages
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
      - name: certificate_subject_name
        in: query
        description: 'Search parties based on the subject name of their PKI (x509) certificates. Usually to find a party who is

          requesting tokens'
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: Parties list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_Party'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
      - bearer_auth: []
    post:
      tags:
      - Parties
      operationId: create_ep
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Party'
        required: true
      responses:
        '201':
          description: Entitled party created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Party'
        '400':
          description: Invalid party data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '409':
          description: Party already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
      - bearer_auth: []
  /api/v1/parties/{party_id}:
    get:
      tags:
      - Parties
      operationId: get_party
      parameters:
      - name: party_id
        in: path
        description: Unique identifier of the party to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Party details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Party'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Party not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
components:
  schemas:
    AgreementStatus:
      type: string
      enum:
      - Draft
      - Signed
      - Accepted
      - Obsolete
    RoleDefinition:
      type: object
      description: 'RoleDefinition : Object which contains details about the iSHARE roles of the party. The details include the level of

        assurance as well as compliance status for each role.'
      required:
      - role
      - start_date
      - end_date
      - loa
      - complaiancy_verified
      - legal_adherence
      properties:
        complaiancy_verified:
          $ref: '#/components/schemas/ComplianceVerified'
          description: Compliance requirements of this role has been met by party
        end_date:
          type: string
          description: UTC timestamp which states till when this role for the party is valid.
        legal_adherence:
          $ref: '#/components/schemas/LegalAdherence'
          description: Legal requirements of this role has been met by party including signing of appropriate agreements
        loa:
          type: string
          description: Party's level of assurance. Available values are low, substantial and high.
        role:
          $ref: '#/components/schemas/Role'
          description: 'Name of the role as defined in iSHARE role framework. Possible roles  are ServiceConsumer, ServiceProvider,

            EntitledParty,  AuthorisationRegistry, IdentityProvider, IdentityBroker and  IdentityBroker and

            ParticipantRegistry, iShareSatellite (deprecated,  will be removed in future releases, use ParticipantRegistry

            instead).'
        start_date:
          type: string
          description: UTC timestamp which states since when this role for the party is valid.
    PartyAdherenceStatus:
      type: string
      enum:
      - Active
      - Pending
      - NotActive
      - Revoked
    DataspaceInfo:
      type: object
      properties:
        count:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of dataspaces returned
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Dataspace'
          description: Object containing dataspace information
        page_count:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of pages (10 per page)
        total_count:
          type:
          - integer
          - 'null'
          format: int32
          description: Total count of found dataspaces
    Certificate:
      type: object
      description: 'Certificate : Object which contains the details of the PKI/x509 certificates of the party.'
      required:
      - subject_name
      - certificate_type
      - enabled_from
      - x5c
      - x5t#s256
      properties:
        certificate_type:
          type: string
          description: type of certificate
        enabled_from:
          type: string
          description: UTC timestamp which states since when certificate is valid.
        subject_name:
          type: string
          description: 'subjectName as encoded in the X.509 certificate which corresponds with the party that is being requested from

            the Participant Registry. Used by the Participant Registry to match the certificate identifier.'
        x5c:
          type: string
          description: The base64 encoded pem format value of the certificate identified by its subject name and fingerprint
        x5t#s256:
          type: string
          description: The SHA256 fingerprint of the certificate
    Party:
      type: object
      required:
      - party_id
      - party_name
      - registrar_id
      - adherence
      - agreements
      - roles
      properties:
        additional_info:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/PartyAdditionalInfo'
        adherence:
          $ref: '#/components/schemas/PartyAdherence'
        agreements:
          type: array
          items:
            $ref: '#/components/schemas/Agreement'
          description: 'Object which contains details about contracts including data space contracts that party has agreed and signed

            to.'
        authregistery:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AuthRegistry'
          description: Object which contains details about the authorization registers that the party uses.
        capability_url:
          type:
          - string
          - 'null'
          description: Capabilities endpoint of the party.
        certificates:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Certificate'
          description: 'Object which contains the details of the PKI/x509 certificates of the party. Either certificates or SPOR must

            be present.'
        party_id:
          type: string
          description: Array of registered party ids of the party.
        party_name:
          type: string
          description: Name of the party.
        registrar_id:
          type: string
          description: Identifier of the party who registered the participant identified by the party_id attribute above
        roles:
          type: array
          items:
            $ref: '#/components/schemas/RoleDefinition'
          description: 'Object which contains details about the iSHARE roles of the party. The details include the level of assurance

            as well as compliance status for each role.'
        spor:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/PartySpor'
    PartySpor:
      type: object
      required:
      - signed_request
      properties:
        signed_request:
          type: string
          description: verifiable credentials of the participant signed by a trusted authority vouching for its authenticity
    LegalAdherence:
      type: string
      enum:
      - 'yes'
      - 'no'
    Dataspace:
      type: object
      properties:
        countries_operation:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Array of country names in which the dataspace operates.
        country_reg:
          type:
          - string
          - 'null'
          description: Country in which the dataspace is registered in.
        dataspace_id:
          type:
          - string
          - 'null'
          description: 'Unique ID of the dataspace. This is in format of <Continent>.<DS>.<3 letter code for

            dataspaces>.<Country>.<dataspace name> for example EU.DS.GND.NL.DVU. Where, continent is 2 letter code,

            followed by “DS” (stands for dataspace), followed by 3 letter code of common eu dataspaces HLT - Health, INM -

            Industrial and Manufacturing, AGR - Agriculture, FIN - Finance, MOB - Mobility, GND - Green Deal, ENR - Energy,

            PUB - Public Administration, SKL - Skills, followed by ISO 3166-1 alpha-2 2 letter Country code and lastly the

            name/title of the dataspace. Name may not contain spaces or dot “.” or other special characters. Maximum length

            of name can be 15 characters.'
        dataspace_title:
          type:
          - string
          - 'null'
          description: Title of dataspace.
        dataspace_website:
          type:
          - string
          - 'null'
          description: 'Website address of the dataspace, typically dataspace authority. The website details out more information about

            the datasapce and guides (potential) participants (to become member of) the dataspace.'
        dataspacedef_url:
          type:
          - string
          - 'null'
          description: 'URL pointing to the dataspace definition. This is expected to be based on OpenDEI model of building blocks for

            dataspaces. The machine redable format definition is currently under development. The specifications will be

            made available once published.'
        sectors:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Array of sector names in which the dataspace operates.
        status:
          type:
          - string
          - 'null'
          description: Status of the dataspace. Available values are new, in progress, active and not active.
        tags:
          type:
          - string
          - 'null'
          description: 'Free text field for addting relevant tags that are relevant in the context of datasapce. It useful for

            searching for specific dataspaces based on tags.'
    Role:
      type: string
      description: 'Name of the role as defined in iSHARE role framework. Possible roles are ServiceConsumer, ServiceProvider,

        EntitledParty, AuthorisationRegistry, IdentityProvider, IdentityBroker and ParticipantRegistry.'
      enum:
      - ServiceConsumer
      - ServiceProvider
      - EntitledParty
      - AuthorisationRegistry
      - IdentityProvider
      - IdentityBroker
      - ParticipantRegistry
      - iShareSatellite
    AuthRegistry:
      type: object
      description: 'AuthRegistry : Object which contains details about the authorization registers that the party uses.'
      required:
      - authorizationRegistryName
      - authorizationRegistryID
      - authorizationRegistryUrl
      properties:
        authorizationRegistryID:
          type: string
          description: The Id of the authorization registry provider
        authorizationRegistryName:
          type: string
          description: The name of the authorization registry provider
        authorizationRegistryUrl:
          type: string
          description: The URL pointer specific to the party where authorizations can be queried/checked from
        dataspaceID:
          type:
          - string
          - 'null'
          description: The id of the data space where the party uses this authorization registry provider
        dataspaceName:
          type:
          - string
          - 'null'
          description: The name of the data space corresponding to the data space id
    Agreement:
      type: object
      description: 'Agreement : Object which contains details about contracts including data space contracts that party has agreed and

        signed to.'
      required:
      - type
      - title
      - status
      - sign_date
      - expiry_date
      - framework
      - complaiancy_verified
      properties:
        agreement_file:
          type:
          - string
          - 'null'
          description: 'The calculated hash of the agreement file that has been uploaded. Note agreements are not stored in ledger, but

            only their hash.'
        complaiancy_verified:
          $ref: '#/components/schemas/ComplianceVerified'
          description: 'Legal compliance to this agreement has been verified in accordance with the process set in trust framework as

            we as data space governance. Possible values are Yes, No, Not Applicable'
        dataspace_id:
          type:
          - string
          - 'null'
          description: 'The ID of the data space. If specified, party is onboarded in accordance to this data space''s terms and

            conditions'
        dataspace_title:
          type:
          - string
          - 'null'
          description: The name of the selected dataspace
        expiry_date:
          type: string
          description: Expiry date of the agreement. For non expiring agreements the end date is far in future
        framework:
          type: string
          description: The trust framework to which this agreement complies to. Currently, only iSHARE is available.
        sign_date:
          type: string
          description: Date of signature of the agreement.
        status:
          $ref: '#/components/schemas/AgreementStatus'
          description: Status of the agreement. Available values are Draft, Signed, Accepted, Obsolete.
        title:
          type: string
          description: The name of the agreement or agreement file
        type:
          type: string
          description: 'Type of agreement. Refers to the official type of agreement. For iSHARE following types are available Terms of

            Use, Accession Agreement, Certified Party Agreement, Participant Registry Agreement  (former name Satellite

            Agreement will be deprecated).  Additionally, each data space can define their own type and it can be listed

            here when appropriate dataspace is chosen'
    PartyAdditionalInfo:
      type: object
      properties:
        company_email:
          type:
          - string
          - 'null'
          description: General company email id of the party
        company_phone:
          type:
          - string
          - 'null'
          description: General company phone number of the party
        countries_operation:
          type:
          - array
          - 'null'
          items:
            type: string
          description: An array of ISO names of the countries where the party operates
        description:
          type:
          - string
          - 'null'
          description: A brief description of the party
        logo:
          type:
          - string
          - 'null'
          description: URL pointing to the endpoint where company logo can be found.
        publicly_publishable:
          type:
          - string
          - 'null'
          description: Consent to publicly publish the information contained in this object
        sector_industry:
          type:
          - array
          - 'null'
          items:
            type: string
          description: An array of GICS based sectors/industry that party serves in
        tags:
          type:
          - string
          - 'null'
          description: An free text field containing keywords relevant for party
        website:
          type:
          - string
          - 'null'
          description: Website address of the party
    ProblemDetail:
      type: object
      required:
      - type
      - status
      properties:
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        status:
          type: integer
          format: int32
          minimum: 0
        title:
          type:
          - string
          - 'null'
        type:
          type: string
      additionalProperties: {}
    PartyAdherence:
      type: object
      required:
      - status
      - start_date
      - end_date
      properties:
        end_date:
          type: string
          description: UTC timestamp which states till when adherence status has established.
        start_date:
          type: string
          description: UTC timestamp which states since when adherence status has established.
        status:
          $ref: '#/components/schemas/PartyAdherenceStatus'
          description: Status of the party. Available values are Active, Pending, NotActive and Revoked.
    Paged_Party:
      type: object
      required:
      - page
      - size
      - page_count
      - total_count
      properties:
        page:
          type: integer
          format: int32
          minimum: 0
        page_count:
          type: integer
          format: int32
          minimum: 0
        records:
          type:
          - array
          - 'null'
          items:
            type: object
            required:
            - party_id
            - party_name
            - registrar_id
            - adherence
            - agreements
            - roles
            properties:
              additional_info:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/PartyAdditionalInfo'
              adherence:
                $ref: '#/components/schemas/PartyAdherence'
              agreements:
                type: array
                items:
                  $ref: '#/components/schemas/Agreement'
                description: 'Object which contains details about contracts including data space contracts that party has agreed and signed

                  to.'
              authregistery:
                type:
                - array
                - 'null'
                items:
                  $ref: '#/components/schemas/AuthRegistry'
                description: Object which contains details about the authorization registers that the party uses.
              capability_url:
                type:
                - string
                - 'null'
                description: Capabilities endpoint of the party.
              certificates:
                type:
                - array
                - 'null'
                items:
                  $ref: '#/components/schemas/Certificate'
                description: 'Object which contains the details of the PKI/x509 certificates of the party. Either certificates or SPOR must

                  be present.'
              party_id:
                type: string
                description: Array of registered party ids of the party.
              party_name:
                type: string
                description: Name of the party.
              registrar_id:
                type: string
                description: Identifier of the party who registered the participant identified by the party_id attribute above
              roles:
                type: array
                items:
                  $ref: '#/components/schemas/RoleDefinition'
                description: 'Object which contains details about the iSHARE roles of the party. The details include the level of assurance

                  as well as compliance status for each role.'
              spor:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/PartySpor'
        size:
          type: integer
          format: int32
          minimum: 0
        total_count:
          type: integer
          format: int32
          minimum: 0
    ComplianceVerified:
      type: string
      enum:
      - 'yes'
      - 'no'
      - partial
      - not applicable
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token obtained from /oauth/token endpoint