Karify API (v2)

Generally speaking, a Karify API application only has access to a user's data after the user has authorized the application to use it.

Registering your application and thereby receiving credentials can be requested only by contacting Karify. These credentials allows you to negotiate tokens on behalf of Karify users. All calls to the Karify API require a token defining the user and application making the call.

See the Authentication section for more information about generating access tokens and the OAuth authorization flow.

Treat tokens with care. Never share tokens with other users or applications. Do not publish tokens in public code repositories.

HTTP headers All API operations use JSON as the data format. To make a request with a JSON body, use the following header in the request:

Content-Type: application/json

If an operation returns JSON data, also add the Accept header to your request. Also, since the only available version is v2, the version should be added to this header:

Accept: application/json; version=v2

API calls indicate the result (success or error) using the corresponding HTTP status codes. See RFC7231 section 6.1 for a list of HTTP status codes.

The response body may have additional error information in the JSON object, for example:

(404 NOT FOUND):

{
  "error_code":"ACCOUNT_NOT_FOUND"
}

Or, when adding information to Karify, the data in the body of the POST or PUT/PATCH request can be unprocessable. Then the following exception will be returned (422 UNPROCESSABLE ENTITY):

{
  "error_code":"VALIDATION_ERROR",
  "details":
  [
    {
      "property_path":
      "emailAddress",
      "message": "This value is not a valid email address.",
      "error_code": "INVALID_EMAIL_FORMAT"
    }
  ]
}

To keep Karify API backwards compatible, some endpoints also return the fields code and message in the exception response. These fields will be deprecated so applications should not create a dependency on it.

In addition to the common error codes, the Karify API can also return the following error codes:

Note that responses may contain user-generated data, which is not escaped or sanitized unless otherwise noted. It could therefore also contain HTML and/or Javascript. You should make sure that this data is sanitized or escaped before rendering, to avoid executing potentially malicious code.

By default, GET operations, which return a list of requested items, return only the first 10 items. To get a different set of items, you can use the offset and limit parameters in the query string of the GET request.

For example, the .../spaces (GET) operation returns:

To page through all the available items, first, use the collection metadata section of the JSON response to get the total number of items.

{
  "collection":
    [
      ...
    ],
  "offset": 0,
  "limit": 10,
  "total_count": 39
}

Tip: You can request .../spaces?limit=0 to get just metadata, without defect data.

Then send subsequent requests with increasing offsets and a fixed limit until you get all the data.

.../spaces?offset=10&limit=10
.../spaces?offset=20&limit=10
.../spaces?offset=30&limit=10

Karify will take effort to making all changes to the Karify API backwards compatible. However, when a breaking change has to be made within a version of the Karify API, we will take care of phasing out the old variant. This means:

• We will mark a functionality as deprecated in the documentation,
• Communicate this deprecation to our clients with clear deprecation plan.
• As communicated in the deprecation plan, we will remove deprecated functions only after the mentioned time window. When possible, we will monitor the usage of deprecated functions to make sure no breaking changes occur client side.

Some API endpoints are currently marked as beta. This means backwards incompatible changes might be made without any deprecation plan or notification upfront.

• Properties can be added to the JSON responses within the same API version, so make sure your application can handle these additional properties.
• Do not use more data than necessary so server load and your application's response time is as low as possible. Also, by using only what is needed, backward compatibility issues will less likely to happen.
• E.g., be cautious with the use of a high limit parameter when paginating responses.
• Do not create unnecessary dependencies on fields that your application does not need.
• Make sure you always set the accept header.
• Make sure you do not parse the response body of responses with a 204 HTTP status code since those responses never contain a body.
• Make sure your application can handle error responses and validation responses well. Logging error responses will help you in finding the actual problem. Also make sure that a client side error (4XX status code) won't block other processes of your application without reason.
• Received access tokens can be invalidated by users in their Karify account settings. Make sure your application handles an invalidated access and refresh token well. Any API endpoint will respond with a 401 Unauthorized response code when an access_token has been invalidated by the user, while refreshing the access_token will result in a 400 Bad Request response code in this situation.

The grant type which will be used to authenticate as a Karify user and therefore being able to view or change data on behalf of that user is the authorization_code grant type. Also see RFC6749.

Authorization consists of two (or three if token is expired) steps before the step of getting, putting or posting content via the API is possible:

• Requesting an (authorization) code
• Exchange (authorization) code for an access_token
• Refresh expired access_token using an refresh_token
• GET, PUT or POST content (Protected Resource) using access_token

Once having a valid access_token it can be used to do requests to Karify API endpoints. Note that access tokens have a lifetime of one hour. Once expired, a 401 Unauthorized will be returned. The response message can be The access token provided has expired. or The access token provided is invalid. since Karify cleans up expired refresh tokens on a regular basis.

See the described steps in the schema below:

Karify has the possibility to start up a Karify session for a user using an OAuth access_token. This makes it possible to set up a Single Sign-On functionality after a user explicitly granted this for your application.

Karify's Single Sign On (SSO) makes easy access for the end-user from an external application to Karify possible (e.g. EPD, HIS or KIS). When an end-user is logged in at a trusted external application, the end-user can be directly redirected to Karify without having to log in again.

Karify makes use of Security Assertion Markup Language 2.0 (SAML) to make SSO possible. SAML is a common standard within healthcare. It is an XML-based, open-standard data format for exchanging authentication and authorization data between applications. Specifically, between an identity provider (IdP) and a service provider (SP). Karify acts as the service provider (SP). Identifying a user with Karify is done based on the email address provided in the SAML response message.

This functionality provides sufficient opportunity for an application to achieve a basic integration with Karify. A more comprehensive integration is possible by using a RelayState, which redirects the end user to a specific page in Karify. For example, to a client's record (see also the section Redirecting to a client's page below.

Karify supports two types of usage scenarios of the SAML protocol:

• IdP-initiated Single Sign-On POST Binding
• SP-initiated Single Sign-On POST/Artifact Bindings

In this scenario the user is able to be redirected directly from an application (IdP) to Karify (SP). A typical example is providing a 'Go to Karify' button in the application, or when utilizing RelayState, a 'Go to client X's dossier in Karify' button.

The following is a typical scenario:

1. The user browses to the external application known as the IdP. The application prompts the user for credentials.
2. The user logs in to the external application.
3. The user clicks on the 'Go to Karify' button. This causes the IdP's Single Sign-On Service to be called.
4. The Single Sign-On Service builds a SAML assertion representing the user's logon security context. The assertion is digitally signed before it is placed within a SAML Response message.
5. The browser issues an HTTP POST request to send the form to the Karify's Assertion Consumer Service (https://saml.karify.com/acs, found in Karify's metadata file).
6. Karify validates the message and checks whether the user exists and has the correct authorization to access the resource.

If the access check passes, the resource is then returned to the browser. In other words: the user is logged in.

In this scenario an SP-initiated SSO exchange is described. In such an exchange, the external application sends the user to a specific page on Karify (e.g. https://saml.karify.com/identity-provider-x). Again, a typical example is a 'Go to Karify' button. Since the user does not have a current logon session for Karify, the user is sent to the IdP to log on and the IdP provides a SAML web SSO assertion for the user's federated identity back to Karify, the SP.

For additional information, see the official documentation on this scenario at http://saml.xml.org/wiki/sp-initiated-single-sign-on-postartifact-bindings.

The following is a typical scenario:

1. The user browses to the external application, known as the IdP. The application prompts the user for credentials.
2. The user logs in to the external application.
3. The user clicks on the 'Go to Karify' button. The external application sends the user to a specific page on Karify (e.g. https://saml.karify.com/identity-provider-x).
4. Karify will start up a SAML request by redirecting the user with sending an AuthRequest to the IdP using HTTP-POST binding.
5. The Single Sign-On Service of the IdP builds a SAML assertion representing the user's logon security context. The assertion is digitally signed before it is placed within a SAML Response message.
6. The browser issues an HTTP POST request to send the form to Karify's Assertion Consumer Service (https://saml.karify.com/acs, found in Karify's metadata file).
7. Karify validates the message and checks whether the user exists and has the correct authorization to access the resource. If the access check passes, the resource is then returned to the browser. In other words: the user is logged in.

Redirecting to a Client's Page

Karify provides an option to redirect users to a specific client's page using the client's identification number, when the current user has a connection with that client. The required URL format is:

https://my.karify.com/client-by-identification-number/{identification-number}

For example, if the client's identification number is 1234abc, the URL would be:

https://my.karify.com/client-by-identification-number/1234abc

When the current account has a connection in one Healthspace, they are immediately redirected to the client's page in that Healthspace. Otherwise a screen is shown with the different Healthspaces (in case of a connection in multiple Healthspaces) or a "not found" message.

Using RelayState with SP-Initiated Single Sign-On

When combining this redirection with SP-initiated Single Sign-On, the RelayState parameter should contain the URL-encoded client page URL. The URL that the user is redirected to in step 3 of the above flow would look like this (mind the identity-provider-x part that should be replaced by the relevant identity provider for your organization):

https://saml.karify.com/authn/identity-provider-x?RelayState=https%3A%2F%2Fmy.karify.com%2Fclient-by-identification-number%2F1234abc

This ensures that after authentication, the user is redirected directly to the client's page in Karify.

Each Karify user has an account, even if a user does not have any membership (profile) for a Healthspace, he or she can still have an account.

Each account endpoint needs its own scope and role permissions. An application can use the scope MANAGE_ORGANIZATION_ACCOUNTS to use all (..._READ) scopes in one scope.

Banners

Karify access authorisation works based on connections. Connections between a clinician and a patient allows record access, communications and managing treatments. Connections are made based from profile to profile so are on the level of a Healthspace. Each user in Karify can requests it's own connections, so both users with an account type staff as an account type client.

Counters

Each user in Karify can requests their own profiles, so both users with an account type staff as an account type client.

Organization owners can generate data exports. A data export consists of several CSV files and a text description of these CSV files, all combined in a zip file. These data exports are generated in an asynchronous process, as the creation can take quite a long time (due to various factors). The workflow is therefore to first create a new data export using the POST /api/v2/data-exports endpoint, then poll the status through the GET /api/v2/data-exports endpoint. Once the status has progressed from queued to processing to finished, the data export will have the download url available, which indicates where the zip file can be downloaded. Finally, a data export can be deleted using the DELETE /api/v2/data-exports/{id} endpoint. Data exports are automatically deleted after 14 days, so deleting manually is not necessary but can keep the overview more organized.

External record items can be added to the personal health record of a client on behalf of an organisation in Karify. Each external record item endpoint needs its own scope and role permissions. An application can use the scope MANAGE_ORGANIZATION_EXTERNAL_RECORD_ITEMS to use all (..._READ, ..._CREATE and ..._UPDATE) scopes in one scope. We distinguish two types of external record items, based on their contents: HTML external record items, and external record items with a file. These are very similar when retrieved through GET requests. However, the POST and PUT requests differ to such a degree that they are specified for both types separately in this documentation.

My Files

Specific users can also manage all connections in a Healthspace (when they have the role ROLE_SPACE_CONNECTION_MANAGER for the given Healthspace).

Each connection endpoint needs its own scope and role permissions. An application can use the scope MANAGE_SPACE_CONNECTIONS to use all (..._READ, ..._CREATE and ..._DELETE) scopes in one scope.