Get started

Create a Manager and a Submitter application in the Console, authenticate to the Signals API, and set up the three Signals settings.

Create the two applications that call Signals' API through Ovok, authenticate with them, and choose your settings.

Open Applications

  1. Sign in to the Console.
  2. Pick your project and its environment.
  3. Open Applications and choose New application.

Your project needs a Signals tenant of its own; see Your Signals tenant.

Manager app

The manager runs your tenant: patients, bands, alerts, users and webhooks. It cannot post readings.

Choose Signals manager, name it, and create it. Copy its id and secret into your secret manager; the Console lists them under the application.

  1. 1Applications lists the client apps for this project.
  2. 2Create a Manager client for reading Signals alerts.
  3. 3Copy the client ID and one-time secret while they are shown.
  4. 4Create a Submitter client for posting readings.
  5. 5Save the Submitter ID and one-time secret for your sender.

Submitter app

The submitter posts readings and reads patients. Use one for each gateway or service that sends readings.

Choose Signals submitter, name it, and copy its id and secret.

Authenticate and get a session token

Either app signs in with its id and secret, in one of two ways. Both reach every /v1/signals/api/* route the app's policy allows.

HTTP Basic, on every call. No token to fetch or renew:

curl --get 'https://api.sandbox.ovok.com/v1/signals/api/alert' \
  --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}"

A token, from the client-credentials grant. Fetch it once and send it as a bearer until it expires:

OVOK_TOKEN="$(
  curl --fail-with-body --silent --show-error \
    --request POST 'https://api.sandbox.ovok.com/oauth2/token' \
    --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}" \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
  | jq -er '.access_token'
)"

curl --get 'https://api.sandbox.ovok.com/v1/signals/api/alert' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

The token represents the app, so it holds the app's capabilities and nothing more.

Settings

Three project settings change how your project uses Signals; Signals settings has the detail. A project admin saves each as a Boolean project setting.

SIGNALS_SEND_AUTO

Sends each Observation created through the FHIR API to Signals. Leave it off if you send readings with your own submitter.

SIGNALS_ANNOTATE_OBSERVATIONS

Writes Signals' alerts and episodes into FHIR as DetectedIssue and Flag. Keep it off when your patients live only in Signals.

SIGNALS_MTLS_ENABLED

Requires a client certificate on every call to /v1/signals/api/*, on top of your credentials, and has Signals present its own on every webhook.

Episodes

An episode groups the breaches of one clinical event into one row, instead of one alert per breach. Turn it on for your tenant with episodicAlerts, then read them with episodes=true on GET /alert:

curl --request PATCH 'https://api.sandbox.ovok.com/v1/signals/api/tenant' \
  --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{"settings":{"episodicAlerts":true}}'

mTLS

Mutual TLS means the client proves who it is with a certificate, as well as the server with its own. With it on, a call without one of your project's registered certificates answers 403, and Signals presents its own certificate on every webhook. See Mutual TLS.

Next

Post a first reading in the Quickstart, or build the alert feed in the tutorial.

Last updated on

On this page