Register Widget

Description

Enables a third-party system to request the addition of a widget to the conneQt Toolbar. Each widget instance is identified by a unique name, which is linked to the authentication identity represented by the provided API Key. Sending subsequent requests to this endpoint using the same name value will update the existing registration.

Important

Once a widget registration has been submitted a manual approval process is required to be completed by Quicksilva. While in integration, please notify us. This approval process is also required for any further widget registration updates.

HTTP Definition

Method: POST Endpoint URL: /api/v1/widgets

Headers

The following HTTP headers are required with this request:

Name Data Type Notes
ApiKey string The unique key issued by Quicksilva to identify your system.
Content-Type string Must define the request content as 'application/json'.

URL Parameters

The request contains no URL parameters.

Request JSON Definition

Name Cardinality Data Type Notes
name 1..1 string The name displayed to toolbar users for this widget.
icon 1..1 string The icon from the Toolbar icon pack used when displaying your widget.
launchUrl 1..1 url The secure (https) URL to which the Toolbar should make HTTP requests for your widget.
encryptionSecret 1..1 string A 32-character UTF-8 string used for encrypting JWT tokens.
encryptionMethod 0..1 string Choose between 'A256GCM' or 'A128CBC_HS256'. Defaults to 'A256GCM' if omitted. Only necessary if your system can't decrypt JWTs encrypted with 'A256GCM'.
requiresUserData 1..1 boolean Specify whether a JWT should be added to the launch URL query string, containing user context data.
requiresPatientData 1..1 boolean Specify whether a JWT should be added to the launch URL query string, containing subject (patient) context data. If not available, the Toolbar user will be prompted. 
POST https://int.conneqt.health/api/v1/widgets HTTP/1.1
Content-Type: application/json; charset=utf-8
ApiKey: <API-KEY-PLACEHOLDER>

{
  "name": "My Widget",
  "icon": "mail",
  "launchUrl": "https://jwt-test-display.azurewebsites.net",
  "encryptionSecret": "HAEISWDHFDHSWAUIDHF8239DH0C0HIAB",
  "requiresUserData": true,
  "requiresPatientData": false
}
Note

The included launchUrl and encryptionSecret provided allow for verification of the data sent within the JWT payload for your initial testing. These should both be updated as part of widget registration.

Note

The Toolbar rejects requests for patient data without user data.

Note

The default encryption method used is A256GCM. Only specify the alternate method A128CBC_HS256 if your system cannot decrypt from the default method, which is a rare case.

Response JSON Definition

This message does not include a response payload.

HTTP/1.1 204 No Content

Error Responses

If there was an issue processing your request, a HTTP error response will be returned, containing details of the issue. Common problems include:

  • One or more invalid data items were found in the request.
  • The intended recipient organisation is not one that uses our system.

The system uses the definition of an IETF Problem, as described in RFC 7807, in error responses to provide machine-readable details of why a request was rejected. The content of the Problem returned depends on the nature of the issue.

HTTP Response Code HTTP Reason Code Description
400 Bad Request Validation issues found in your request.
401 Unauthorized Missing or Invalid API Key in the Request Header.
403 Forbidden Unauthorized Client System - The Provided API Key Is Valid but Not Authorized.
500 Internal Server Error Internal Server Error - An Internal Server Error Prevented the Request from Being Processed.

See Also