Overview

Particle clients typically fall under 2 main categorizations: (1) those that are themselves a "Covered Entity" (CE) and (2) those that provide their services to and hold BAAs with CE's. For the latter, it's important for our client's to be able to effectively manage network requirements by classifying which CE is querying for a Patient's data.

This document outlines how you are able to utilize our Management APIs to manage data access for each entity that you are providing data to downstream. Please reach out to your Particle Health representative with any questions that you may have.

Term Definitions

Organization Domain Model

Organization: An Organization is typically you as our client! Organizations are, in a majority of cases, not considered Covered Entities (CE) themselves, but have Business Associate Agreements (BAAs) with CEs. An Organization provides some form of service to their clients or downstream users of the clinical data we provide. The most common example of this is a Health IT platform that sells its services to clients of their own, but may vary depending on use case and your business model. The Particle Health team will help you in navigating whether or not you fall into this designation and if our Management API solution is right for you.
Project: A Project is the entity that will ultimately be using the data that we provide. Projects are Covered Entities themselves and are typically involved in the direct treatment relationship with a patient. Organizations query on behalf of Projects.
Connection: A Connection can be thought of as an individual location within a broader institution. Tri-State Medical Group, for example, may have dozens of doctor's offices spread across New York, New Jersey, and Connecticut. Connections are a way to define, within a single project, whether or not there are multiple locations where care is given under that Project’s umbrella.

This diagram illustrates the hierarchy of Organizations <> Projects <> Connections:

🚧
Note: the Particle Management APIs will only be relevant to your organization if you fall into the "Client A" or "Client C" categorization diagramed above. If you have any questions about your designation as a Particle client, please reach out to your Particle Health team.

Main Query Flow

The Particle Main Query Flow (MQF) is how Patient queries are initiated and data is downloaded. These are the core actions that allow our customers to submit patient demographic information, download FHIR, CCDA, and/or Flat data formats, and fulfill Bi-Directionality requirements

Management APIs

Particle’s Management APIs are used to administer and manage the configuration and network access of entities that require patient data.

The Management APIs assist in:

Full management of Projects and their network access
Connection management
Generation and rotation of access Credentials
Service Account creation and management (defined below)
Service Account access management (defined below)
Managing Notification (Webhook) configuration (coming soon…)

Service Accounts (SA)

A Service Account is a mechanism to control how customers of ours interact with their organizations, projects, connections, and credentials. SAs have a IAM Policy & single set of credentials associated with them and can be scoped to allow access to a single or set of Projects.

Service Accounts can have the following IAM Policy Roles:

organization.owner: grants the SA full access to all Management API operations, including creating other SAs, generating credentials, creating projects and connections, and associating Projects with SAs. Organization Owner SAs cannot access the MQF APIs. More information on this can be found below.
project.owner: grants the SA full access to all Management API operations under the Project or set of Projects that the SA grants access to. Project Owner SAs can access the MQF APIs.
project.user: grants the SA access to the MQF APIs only.

Service Accounts and the strategy for using them is meant to be flexible depending on our clients needs from a use case and security perspective. One of our recommended methods for SA management is detailed below, but your Particle Team can work with you to design a system that works best for you.

Credentials

Credentials are used to fulfill the OAuth 2.0 access pattern that we require our clients to follow. Credentials (Client ID + Client Secret) are used to generate JSON Web Tokens (JWTs) for the purposes of authenticating calls to our Management APIs and Main Query Flow APIs.

Credentials are tied 1:1 to Service Accounts and JWTs are used as authentication tokens for all calls to our API (excluding /auth).

Configuring Organization Projects

📘
Please reach out to your Particle Health representative for more information about enabling the ability to create and query on behalf of multiple projects.

❗️
Note that the upper bounds on the number of projects that can be added via our Management API will be set to 10. If you anticipate needing more, please work with your Particle Health team to explore raising that limit.
Additionally, there may be scenarios where the Management API is not appropriate for your Organization <> Project setup. Your account team will work with you to identify the best method for adding new projects to the directories.

Using the Client ID & Secret provided to you by your Particle Health representative, call the /auth endpoint to generate a JWT. This JWT can only be used for Management API operations (e.g. creating Projects, creating new Service Accounts, associating Service Accounts to projects, etc.)
Call the Create New Project (POST /v1/projects ) endpoint with the name, location, and NPI information for that institution (e.g. practice, individual provider, your client, etc.)
1. Note the project name in the response; this name will follow the projects/{UUID} pattern and will be used for all subsequent operations for that particular project
2. Repeat this operation for every project that you would like to add. Note that clients are required to maintain a mapping of these Project UUIDs for the purpose of making queries on behalf of that project.
3. Setting state:
  1. If set to active, the Project will be ready to query the networks in 48hrs
  2. If set to inactive, the Project will need to be set to active in order to be activated on the network. To update the state, call v1/project/{UUID} and change the state to active.
Once a Project or set of Projects have been created, call the Create new Service Account (POST v1/serviceaccounts ) endpoint. Note the SAs name (in the format of /serviceaccounts/{UUID} in the POST response.
Set the Policy of the newly created Service Account via the POST /v1/serviceaccounts/{UUID}:setPolicy endpoint
1. Set role to roles/project.owner
  1. Other role types are available as well. Please work with your Particle Health team to determine which path is right for you.
2. Set the resources array to include all relevant project names
```
{
    "bindings": [
        {
            "role":"roles/project.owner",
            "resources": [
                "projects/UUID_1",
                "projects/UUID_2",
                "projects/UUID_3",
                "projects/UUID_n"
            ]
        }
    ]
}
```
3. Whenever a new Project is created after this initial set of steps, update the SA Policy by calling this endpoint again with any additional Projects that need to be added to the resources array. The recommended flow for this is to GET an SAs current policy then re-set the same SAs policy with all previously added resources and any additional projects you’d like to add to the resources array.
4. **Assigning all Projects to a single Service Account is just one of many strategies to managing how SAs are used to query for patient data. The Particle Health team can work with you to determine which strategy works the best for you and your use case.
Create a new set of Credentials under this Service Account by calling the POST /serviceaccounts/{UUID}/credentials endpoint and note the clientId and clientSecret in the response.
1. ***the clientSecret must be saved on the client side at this point and will only be accessible once. If a new set of credentials is needed, you must rotate the credential (more information on this can be found below).
2. These credentials will be used for the Main Query Flow (a.k.a. patient data retrieval) and have no pre-defined expiration time. If desired, clients can choose to rotate their credentials at a cadence that makes the most sense for their workflow and security requirements. Your Particle Health can advise you on best practices and any questions.
Begin querying for Patient data; more information for this flow can be found below.

Executing Patient Queries

Using the clientId and clientSecret generated during Step 6 of the “Configuring Organization Projects” sequence, call the /auth endpoint to generate a JWT
1. The scope of the Project (projects/{UUID}) you’d like to query on behalf of MUST be passed during this step.
2. The resultant JWT will be scoped for that Project and that Project only. This follows token security best-practices.
3. JWTs expire after 60mins and must be re-generated after that time. Your Particle Health team can guide you on JWT management best-practices.
Using the resultant JWT, begin querying for patient data according to our Recommended Query Flow
1. Note that this JWT will, for example, only be valid for queries on Project A . If you’d like to make queries on behalf of Project B, the scope for Project B must be passed in the JWT generation step.
2. Your Particle Health team is here to assist you on Patient query strategies.

Adding Connections to a Project

This section walks through how to add a Connection or a set of Connections to a Project.

Call the Create a new Connection (POST /v1/projects/{UUID}/connections) with information related to that Connections location; this will be added in the connection object.
1. Connections must be marked as active
That’s it! Full CRUD operations are available on Connections and can be updated at any time.

Rotating Credentials

Clients also have the ability to rotate credentials related to a Service Account at any time. This section walks through how to rotate credentials programmatically.

Call the Create Credentials under Service Account (POST /serviceaccounts/{UUID}/credentials) and note the clientId and clientSecret in the response body.
1. If you’d like to expire the old credential immediately, set oldCredentialTtlHours to 0
2. If you’d like to expire the old credential after a set period of time (e.g. to give you time to update your production query flow without interruption) set oldCredentialTtlHours to your desired expiration time (in hours). An integer of 0 through 24 , inclusive, can be passed through to set the old credential expiration time.
3. If nothing is passed to oldCredentialTtlHours, the expiration time will be set to 24 by default.
That’s it! Your credential is now updated.