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 ..<3 letter code for dataspaces>.. 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