swagger: "2.0"
info:
  description: "Allows a third-party system to request a widget be added to the Quicksilva Toolbar. Every widget instance is identified by it's unique name linked to the authentication identity represented by the provided API Key, sending susequent requests to this endpoint using the same name value will cause the existing registration to be updated. Updates are subject to re-approval"
  version: "1.0.0"
  title: "IM1 Toolbar Widget Services"
  contact:
    email: "info@qxlva.com"
host: "toolbar.widget.io"
basePath: "/api/v1"
tags:
  - name: "Widget Registration"
    description: "Widget registration services"
    externalDocs:
      description: "Find out more"
      url: "https://docs.quicksilva.info/toolbar/articles/widgets/index.html"   
schemes:
  - "https"
  - "http"
paths:
  /widgets:
    post:
      tags:
        - "Widget Registration"
      summary: "Requests the addition of a widget to the toolbar"
      operationId: "registrationRequest"
      consumes:
        - "application/json"
      parameters:
        - in: "body"
          name: "Registration Request"
          description: "The registration request"
          required: true
          schema:
            $ref: "#/definitions/RegistrationRequest"
      responses:
        "204":
          description: "Success"
        "400":
          description: "Bad Request"
          schema:
            $ref: "#/definitions/InvalidParametersProblem"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden.  Supplied authorization material is valid, but access to this resource is forbidden."
      security:
        - ApiKey: [ ]
  /public-keys:
    get:
      tags:
        - "Public Keys"
      summary: "Endpoint for public keys used to verify signature on JWTs generated by this service"
      operationId: "publicKeys"
      produces:
        - "application/json"
      responses:
        "200":
          description: "Success"
          schema:
            $ref: "#/definitions/PublicKeys"
      security:
        - ApiKey: [ ]
securityDefinitions:
  ApiKey:
    type: "apiKey"
    name: "ApiKey"
    in: "header"
definitions:
  RegistrationRequest:
    type: "object"
    required:
      - "name"
      - "icon"
      - "launchUrl"
      - "encryptionSecret"
      - "requiresUserData"
      - "requiresPatientData"
    properties:
      name:
        type: "string"
        description: "The name of the widget as it will be displayed to toolbar users.  If that name is already used elsewhere, a 'Bad Request' will result"
        example: "PatientDataExportWidget"
        minLength: 1
        pattern: "^[A-Za-z0-9 _\\-]*$"
      icon:
        type: "string"
        description: "Which icon from the Toolbar icon pack should be used when displaying your widget"
        example: "PulseDisplayIcon"
        minLength: 1
      launchUrl:
        type: "string"
        description: "The URL the Toolbar should make HTTP requests to, must be secure (https)"
        example: "https://mycompany.com/patientDataWebApp/context"
        minLength: 1
        pattern: "[(http(s)?):\\/\\/(www\\.)?a-zA-Z0-9@:%._\\+~#=]{2,256}\\.[a-z]{2,6}\\b([-a-zA-Z0-9@:%_\\+.~#?&//=]*)"
      encryptionSecret:
        type: "string"
        minimum: 32
        maximum: 32
        description: "The string secret to be used for encrypting JWT tokens, must be exactly 32 UTF-8 characters in length"
        example: "HAEISWDHFDHSWAUIDHF8239DH0C0HIAB"
        minLength: 1
      requiresUserData:
        type: "boolean"
        description: "Whether a JWT should be appended to the launch URL query string containing data for the current user context"
        example: "true"
      requiresPatientData:
        type: "boolean"
        description: "Whether a JWT should be appended to the launch URL query string containing data for the current subject context"
        example: "true"
  Problem:
    description: A Problem Details object, as specified in RFC 7807
    type: object
    properties:
      type:
        type: string
        format: uri
        description: A URI reference [RFC3986] that identifies the problem type and may be de-referenced for a human readable explanation of the error type.
        default: about:blank
        example: "https//qxlva.com/im1toolbar/documentation/api/v1/validation-error"
      title:
        type: string
        description: A short, human-readable summary of the problem type.  It SHOULD NOT change from occurrence to occurrence of the problem.
        example: "Request Validation Error"
      status:
        type: integer
        format: int32
        description: The HTTP status code generated by the origin server for this occurrence of the problem.
        minimum: 400
        maximum: 600
        exclusiveMaximum: true
        example: 400
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem
        example: "Invalid parameters"
      instance:
        type: string
        format: uri
        description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced. Please use as a reference in support queries.
        example: "22835b83-1050-49d2-9a46-ae71768150dc"
  InvalidParametersProblem:
    description: Problem details for invalid input parameter(s)
    type: object
    allOf:
      - $ref: "#/definitions/Problem"
    properties:
      invalidParams:
        type: array
        description: An array of parameter OpenAPI violations
        items:
          $ref: "#/definitions/InvalidParameter"
  InvalidParameter:
    type: object
    properties:
      name:
        description: Invalid parameter name
        type: string
        example: "entity-id"
      reason:
        description: A message detailing the nature of the invalidity
        type: string
        example: "Entity with entity ID cannot be located"
      value:
        description: The value of the invalid parameter
        example: "1f5fd6f0-347e-4df7-be02-5bd51232a29a"
  PublicKeys:
    type: object
    properties:
      keys:
        type: array
        description: "Public keys"
        items:
          $ref: "#/definitions/PublicKey"
  PublicKey:
    type: object
    properties:
      kty:
        type: string
        description: "Key Type - identifies the cryptographic algorithm family used with the key"
        example: "RSA"
      x5t#S256:
        type: string
        description: "X.509 certificate SHA-256 thumbprint"
        example: "tOyQRryl66Zz9AdcN19S6c2fArmVPZxyctxIAZUI4lU"
      e:
        type: string
        description: "RSA private key public exponent"
        example: "AQAB"
      use:
        type: string
        description: "Public key use - identifies the intended use of public key"
        enum:
          - sig
          - enc
      kid:
        type: string
        description: "Key ID - used to match a specific key"
        example: "99311738"
      x5c:
        type: array
        description: "X.509 certificate chain(s)"
        items:
          allOf:
            - type: string
              description: "X.509 certificate chain"
              example: >
                MIIIATCCBumgAwIBAgITXAAAAD6/DT/U50a7vwAAAAAAPjANBgkqhkiG9w0BAQsFADCBnzEVMBMGCgmSJomT8ix
                kARkWBWxvY2FsMR4wHAYKCZImiZPyLGQBGRYORVBTLVBSLUNBLVNIQTIxMjAwBgNVBAMTKU5IU1Njb3RsYW5kIG
                VQaGFybWFjeSBUZXN0IEF1dGhlbnRpY2F0aW9uMTIwMAYDVQQDEylOSFNTY290bGFuZCBlUGhhcm1hY3kgVGVzd
                CBBdXRoZW50aWNhdGlvbjAeFw0xOTAyMTMxMjI4NDFaFw0yOTAyMTAxMjI4NDFaMIGJMQswCQYDVQQGEwJHQjER
                MA8GA1UECBMIU2NvdGxhbmQxEjAQBgNVBAcTCUVkaW5idXJnaDEgMB4GA1UEChMXTkhTUyBlUGhhcm1hY3kgU2V
                ydmljZXMxHjAcBgNVBAsTFUVQUyBQaGFybWFjeSBUZXN0IE1FUDERMA8GA1UEAxMIOTkzMTE3MzgwggEiMA0GCS
                qGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDobkRt/kUBnkbxE+G2/cLdruqxI/BZ0Jg82XuxNoN8nSpsH6/TJdl3Q
                29PuXu+CgmpEA7phe7yU3S1fCZ4AHdc88cMRtMWsgSeiqNnCs6hb2ppUsvO9lWU7LnmbP49sG7+e1mUnvILLxwC
                OFoeEIQ+aQJI80wwJMr96YFAdu+eOGhHKt4GzcwSlEWWjcQfm+SB9UJizQMy1fkDrnIlKYGT4dDlpsxwqJMnwTS
                KBj7crXXMnr6rX6g2ihPT1tqaGUP/lnOl8AnrErGqj3siUevf4Y+EX2czV6gDb2VdFfA7aye4yhpM4490xi0V/w
                lbc1ZspIHfSQaKS7tcqcCDF2sdAgMBAAGjggRIMIIERDALBgNVHQ8EBAMCBaAwOgYJKwYBBAGCNxUHBC0wKwYjK
                wYBBAGCNxUIgoPiC4W15i6GkYs0x4hGh54LGYLB/ETO1AoCAWQCAQMwgZQGCSqGSIb3DQEJDwSBhjCBgzAOBggq
                hkiG9w0DAgICAIAwDgYIKoZIhvcNAwQCAgCAMAcGBSsOAwIHMAoGCCqGSIb3DQMHMAsGCWCGSAFlAwQBKjALBgl
                ghkgBZQMEAS0wCwYJYIZIAWUDBAEWMAsGCWCGSAFlAwQBGTALBglghkgBZQMEAQIwCwYJYIZIAWUDBAEFMB0GA1
                UdDgQWBBR6m2sVaDbfwRSkDYLbqjAl0BwHsjAfBgNVHSMEGDAWgBQhEQf0x2k7XCrYv0GBmpxmHVvNezCBywYDV
                R0fBIHDMIHAMIG9oIG6oIG3hldodHRwOi8vd3d3LmVwcy5uZHMuc2NvdC5uaHMudWsvQ0wvMi9OSFNTY290bGFu
                ZCUyMGVQaGFybWFjeSUyMFRlc3QlMjBBdXRoZW50aWNhdGlvbi5jcmyGXGh0dHA6Ly93d3cuZXBzYmF0Y2gubmR
                zLnNjb3QubmhzLnVrL0NMLzIvTkhTU2NvdGxhbmQlMjBlUGhhcm1hY3klMjBUZXN0JTIwQXV0aGVudGljYXRpb2
                4uY3JsMIICBgYIKwYBBQUHAQEEggH4MIIB9DCB1wYIKwYBBQUHMAKGgcpsZGFwOi8vL0NOPU5IU1Njb3RsYW5kJ
                TIwZVBoYXJtYWN5JTIwVGVzdCUyMEF1dGhlbnRpY2F0aW9uLENOPUFJQSxDTj1QdWJsaWMlMjBLZXklMjBTZXJ2
                aWNlcyxDTj1TZXJ2aWNlcyxDTj1Db25maWd1cmF0aW9uLERDPUVQUy1QUi1DQS1TSEEyLERDPWxvY2FsP2NBQ2V
                ydGlmaWNhdGU/YmFzZT9vYmplY3RDbGFzcz1jZXJ0aWZpY2F0aW9uQXV0aG9yaXR5MIGHBggrBgEFBQcwAoZ7aH
                R0cDovL3d3dy5lcHMubmRzLnNjb3QubmhzLnVrL0NMLzIvTEFQVldFUEhUQ0FYMDIuRVBTLVBSLUNBLVNIQTIub
                G9jYWxfTkhTU2NvdGxhbmQlMjBlUGhhcm1hY3klMjBUZXN0JTIwQXV0aGVudGljYXRpb24uY3J0MIGNBggrBgEF
                BQcwAoaBgGh0dHA6Ly93d3cuZXBzYmF0Y2gubmRzLnNjb3QubmhzLnVrL0NMLzIvTEFQVldFUEhUQ0FYMDIuRVB
                TLVBSLUNBLVNIQTIubG9jYWxfTkhTU2NvdGxhbmQlMjBlUGhhcm1hY3klMjBUZXN0JTIwQXV0aGVudGljYXRpb2
                4uY3J0MB8GA1UdJQQYMBYGCCsGAQUFBwMCBgorBgEEAYI3CgMMMCkGCSsGAQQBgjcVCgQcMBowCgYIKwYBBQUHA
                wIwDAYKKwYBBAGCNwoDDDANBgkqhkiG9w0BAQsFAAOCAQEAFgG4goI5IDd4gH/Vdg/fPiGyky17acnaj5UOHpiY
                JSQuAQlnF+3xOwkfXMS1JeJUkv3LQEhHI9pbT5FN/s6bAgfA2UTliMAeHEEGx5cg/rXh/SQ63fluG96WId2ozoz
                22jCafgdgLDRgkpYCNafwy4SM2lm1adPVNRgxzM4vhY9FMkPmMJR2mQ8laOufBUyV+tfvB8TZXRa3wmQouEtp9f
                8QM8NLsHCCQ6PbKTsr9KEOEIkCb3jrxZKoE6B+MHBKp7W6H/rFa0WkMrKIUKSrvZ3sLYBz4dAQXvwPXoMlg83KR
                taju6KoQL+jcruAb/YXi6MQKwIUX+Y1Up9CpnTfkA==
      n:
        type: string
        description: "Private key modulus"
        example: >
          6G5Ebf5FAZ5G8RPhtv3C3a7qsSPwWdCYPNl7sTaDfJ0qbB-v0yXZd0NvT7l7vgoJqRAO6YXu8lN0tXwmeAB3XPPHDEbTF
          rIEnoqjZwrOoW9qaVLLzvZVlOy55mz-PbBu_ntZlJ7yCy8cAjhaHhCEPmkCSPNMMCTK_emBQHbvnjhoRyreBs3MEpRFlo
          3EH5vkgfVCYs0DMtX5A65yJSmBk-HQ5abMcKiTJ8E0igY-3K11zJ6-q1-oNooT09bamhlD_5ZzpfAJ6xKxqo97IlHr3-G
          PhF9nM1eoA29lXRXwO2snuMoaTOOPdMYtFf8JW3NWbKSB30kGiku7XKnAgxdrHQ
externalDocs:
  description: "Find out more about IM1 Toolbar"
  url: "https://docs.quicksilva.info/toolbar/index.html"