KPN FIAM API

openapi: 3.1.0
info:
  title: FIAM-KPN
  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
paths:
  /api/v1/authorization/enforce:
    get:
      tags:
        - Authorization
      operationId: enforce_authorization
      parameters:
        - name: subject
          in: query
          description: Subject requesting access (maps to target.accessSubject)
          required: true
          schema:
            type: string
        - name: resources
          in: query
          description: Resources being accessed (maps to target.resource.identifiers)
          required: true
          schema:
            type: array
            items:
              type: string
        - name: actions
          in: query
          description: Action being performed (maps to target.actions)
          required: true
          schema:
            type: array
            items:
              type: string
        - name: resource_type
          in: query
          description: Resource type (maps to target.resource.type) - e.g., "API", "API2"
          required: true
          schema:
            type: string
        - name: attributes
          in: query
          description: Resource attributes being accessed (maps to target.resource.attributes)
          required: false
          schema:
            type: array
            items:
              type: string
        - name: issuer
          in: query
          description: Policy issuer (maps to policyIssuer)
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: service_provider
          in: query
          description: Service provider for environment constraints
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: license
          in: query
          description: License context for policy set matching
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Authorization decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Forbidden access
          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:
        - Authorization
      operationId: enforce_authorization_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
        required: true
      responses:
        '200':
          description: Authorization decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Forbidden access
          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/contracts/validate:
    post:
      tags:
        - Contract Validation
      operationId: validate_contract_access
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractValidationRequest'
        required: true
      responses:
        '200':
          description: Validation result returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractValidationResponse'
        '400':
          description: Invalid validation request
          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: [ ]
  /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/oauth/token:
    post:
      tags:
        - Authentication
      operationId: access_token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AccessTokenParams'
        required: true
      responses:
        '200':
          description: Access token successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          description: Invalid token request 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'
  /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'
  /api/v1/service-consumers/contracts:
    get:
      tags:
        - Service Consumer Contracts
      operationId: get_contracts_sc
      responses:
        '200':
          description: List of accessible contracts returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_Contract'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          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/service-consumers/contracts/{contract_id}:
    get:
      tags:
        - Service Consumer Contracts
      operationId: get_contract_sc
      parameters:
        - name: contract_id
          in: path
          description: Contract ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Contract details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Contract not found
          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/service-providers/contracts:
    get:
      tags:
        - Service Provider Contracts
      operationId: list_contracts_sp
      parameters:
        - name: data_owner
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: service_consumer
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: resource_type
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: List of contracts returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_Contract'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          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:
        - Service Provider Contracts
      operationId: create_contract_sp
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewContract'
        required: true
      responses:
        '201':
          description: Contract created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '400':
          description: Invalid contract data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          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/service-providers/contracts/{contract_id}:
    get:
      tags:
        - Service Provider Contracts
      operationId: get_contract_sp
      parameters:
        - name: contract_id
          in: path
          description: Contract ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Contract details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Contract not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
        - bearer_auth: [ ]
    put:
      tags:
        - Service Provider Contracts
      operationId: update_contract_sp
      parameters:
        - name: contract_id
          in: path
          description: Contract ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContract'
        required: true
      responses:
        '200':
          description: Contract updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '400':
          description: Invalid contract data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Contract not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
        - bearer_auth: [ ]
    delete:
      tags:
        - Service Provider Contracts
      operationId: delete_contract_sp
      parameters:
        - name: contract_id
          in: path
          description: Contract ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Contract deleted successfully
        '401':
          description: Unauthorized client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Contract not found
          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/service-providers/parties:
    get:
      tags:
        - Service Provider Parties
      operationId: get_service_provider_parties
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
      responses:
        '200':
          description: Service consumer parties with contracts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_ServiceConsumerParty'
        '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'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
        - bearer_auth: [ ]
components:
  schemas:
    AccessToken:
      type: object
      properties:
        access_token:
          type:
            - string
            - 'null'
        expires_in:
          type:
            - integer
            - 'null'
          format: int64
        token_type:
          type:
            - string
            - 'null'
    AccessTokenParams:
      type: object
      description: struct for passing parameters to the method [`access_token`]
      required:
        - grant_type
        - scope
        - client_id
        - client_assertion_type
        - client_assertion
      properties:
        client_assertion:
          type: string
          description: Used for all client identification for OAuth/OpenID Connect. MUST contain JWT, signed by the client certificate.
        client_assertion_type:
          type: string
          description: |-
            Used for all client identification for OAuth/OpenID Connect.
            MUST contain “urn:ietf:params:oauth:client-assertion-type:jwt-bearer”
        client_id:
          type: string
          description: |-
            Used for all client identification  OAuth/OpenID Connect.
            MUST contain a valid party identifier of the Service Consumer
        grant_type:
          type: string
          description: OAuth 2.0 grant type. MUST contain “client_credentials”
        scope:
          type: string
          description: |-
            OAuth 2.0 scope. MUST contain DSH_FIAM scope value. Other values allow the Service Consumer to get tokens that do
            not include all rights the Service Consumer has. According to RFC 6749, scopes are case-sensitive.
    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
        - fr

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kpn/refs/heads/main/openapi/kpn-fiam-openapi.yml