openapi: 3.2.0
info:
  version: 2.2.2
  title: BoB.. Participant Metadata API
  description: The Participant Metadata API provides an interface for participants to manage metadata coordinated by an Administering Body (AB).
servers:
- url: /api/v2
tags:
- name: participantMetadata
  description: Get all metadata for a certain participant.
paths:
  /participantMetadata/{pid}:
    get:
      tags:
      - participantMetadata
      summary: Get participant metadata by participant identifier
      operationId: getParticipantMetadata
      parameters:
      - name: pid
        in: path
        description: Participant identifier
        required: true
        schema:
          type: integer
          format: int64
      security:
      - Pop: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/participantMetadata'
        '401':
          description: unauthorised
        '404':
          description: pid not found
components:
  schemas:
    endpoint:
      allOf:
      - required:
        - endpointId
      - properties:
          endpointId:
            type: integer
            format: int64
            example: 1
      - $ref: '#/components/schemas/endpointCall'
    issuerSignatureConstraint:
      type: object
      required:
      - pid
      properties:
        pid:
          description: PID of acceptable issuer
          type: integer
          format: int64
          example: 20
        signatureLifetime:
          description: Maximum signature life-time allowed for this PID as ISO 8601:2004 duration format (<a href="https://bitbucket.org/samtrafiken/bob-mts-8-date-and-time-formats/src/master/mts8.pdf" target="_blank">MTS8</a>, chapter 2.4)
          type: string
          example: P3W
    participantInfo:
      description: Holds participant info. Specified in https://bitbucket.org/samtrafiken/bob-schema-participant-info/src/master/participant-info.json
      type: object
    endpointCall:
      type: object
      required:
      - version
      - type
      - uri
      properties:
        version:
          type: integer
          format: int32
          description: A positive integer
          example: 1
        type:
          type: string
          enum:
          - account
          - authentication
          - booking
          - device
          - inspection
          - product
          - resource
          - ticket
          - token
          - traveller
          - validation
          example: ticket
        uri:
          type: string
          example: https://bob.linkon.se/sj/api/v1
        tlsa:
          description: TLSA (<a href="https://tools.ietf.org/html/rfc6698" target="_blank">RFC 6698</a>) parameters for endpoint. More information about TLSA can be found in the <a href="https://samtrafiken.atlassian.net/wiki/spaces/BOB/pages/879067159/Network+Infrastructure+and+Gateways" target="_blank">BoB Manual&#58; Implementer considerations &rarr; Network Infrastructure and Gateways</a>.
          type: object
          properties:
            usage:
              type: integer
              format: int32
              minimum: 0
              maximum: 255
            selector:
              type: integer
              format: int32
              minimum: 0
              maximum: 255
            type:
              type: integer
              format: int32
              minimum: 0
              maximum: 255
            data:
              type: string
              pattern: ^(([0-9A-Fa-f]){2})+$
    jwkPublic:
      type: object
      description: Public JSON Web Key (JWK) as defined in <a href="https://tools.ietf.org/html/rfc7517" target="_blank">RFC 7517</a>. Two algorithms are supported&#58; the primary algorithm is EC (kty=EC) and the fallback algorithm is RSA (kty=RSA).
      required:
      - kty
      - kid
      properties:
        kty:
          type: string
          description: JWA key type
          example: EC
        kid:
          type: string
          description: JWK key identifier
          example: 34:20190101_bob_mtb
        crv:
          type: string
          description: Curve type (required for kty=EC)
          example: P-256
        x:
          type: string
          description: EC x coordinate (required for kty=EC)
          example: MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4
        y:
          type: string
          description: EC y coordinate (required for kty=EC)
          example: 4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM
        n:
          type: string
          description: RSA modulus parameter (required for kty=RSA)
          example: 0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbW...
        e:
          type: string
          description: RSA exponent parameter (required for kty=RSA)
          example: AQAB
    participantMetadata:
      type: object
      required:
      - pid
      - organisationName
      properties:
        pid:
          description: Participant identifier
          type: integer
          format: int64
          example: 20
        organisationName:
          description: Organisation name
          type: string
          example: SJ
        domainName:
          description: Fully qualified domain name (FQDN)
          type: string
          example: sj.se
        mtbPublicKeys:
          description: Public components of current MTB signing keys
          type: array
          items:
            $ref: '#/components/schemas/jwkPublic'
        authtokenPublicKeys:
          description: Public components of current auth token signing keys
          type: array
          items:
            $ref: '#/components/schemas/jwkPublic'
        interfaceEndpoints:
          description: Location of available endpoints
          type: array
          items:
            $ref: '#/components/schemas/endpoint'
        issuerSignatureConstraints:
          description: Acceptable issuers of MTBs
          type: array
          items:
            $ref: '#/components/schemas/issuerSignatureConstraint'
        participantInfo:
          $ref: '#/components/schemas/participantInfo'
  securitySchemes:
    Pop:
      description: OAuth 2.0 Proof-of-possession (pop) Token
      type: apiKey
      name: Authorization
      in: header