Roles

A Role defines an access policy that can be assigned to any number of Developers, Users, and M2M Clients.

For example, you might have a role named "providers" which you give to all of the doctor Users who use your EHR app:

Example Provider Role

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "providers",
  "description": "Grants permission to read and search all FHIR resources, and CRUD Encounters and Observations.",
  "accessPolicy": {
    "rule": [
      {
        "resource": ["FHIR:*"],
        "action": ["FHIR:Read", "FHIR:Search"],
        "effect": "Allow"
      },
      {
        "resource": ["FHIR:Encounter:*", "FHIR:Observation:*"],
        "action": ["FHIR:*"],
        "effect": "Allow"
      }
    ]
  }
}

Using Roles

Creating a Role

To get started with Roles, create a role using any of the Developer Console, SDK, or API endpoint:

Create a Role with the v3 SDK

import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});
 
const role = await oystehr.role.create({
  name: 'Full FHIR Access',
  accessPolicy: {
    rule: [
      {
        resource: ['FHIR:*'],
        action: ['FHIR:*'],
        effect: 'Allow',
      },
    ],
  },
});

Assigning a Role

Once you have created a Role, you can assign it to Developers, Users, and M2M Clients. For example, here's how you can assign a role to an M2M Client:

Assign a role to an M2M Client with the v3 SDK

import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});
 
const updatedM2m = await oystehr.m2m.update({
  id: '23357fe7-3362-484d-a040-a6e572d59de1',
  name: 'SuperAdminM2M',
  accessPolicy: {
    rule: [],
  },
  roles: ['3daa3a95-5aad-4e28-aabb-86a161324d5c'],
});

In the example, 3dda3a95-5aad-4e28-aabb-86a161324d5c is the ID of the role you want to assign to the M2M Client. The Role ID is returned to you when you create the Role. You can also find Role ID in the Developer Console, or fetch them with the API or SDK using the List (opens in a new tab) and Get (opens in a new tab) endpoints.

Using Roles with Zambda (Execution Roles)

Zambdas can be assigned an execution role to automatically receive an access token with limited permissions. When a Zambda has an execution role, the access token is provided directly in the event payload.

Setting an execution role:

const zambda = await oystehr.zambda.create({
  name: 'read-only-zambda',
  triggerMethod: 'http_auth',
  executionRoleId: 'role-uuid-here'
});

Using the access token in your Zambda:

import Oystehr from '@oystehr/sdk';
 
exports.index = async function(event, context) {
  // Access token is automatically provided when execution role is set
  const { accessToken, secrets } = event;
 
  if (accessToken) {
    // Initialize SDK with the execution role's access token
    const oystehr = new Oystehr({
      accessToken: accessToken,
    });
 
    // Use the SDK to make API calls with role's permissions
    const patientBundle = await oystehr.fhir.search<Patient>({
      resourceType: 'Patient',
      params: [
        {
          name: '_count',
          value: '10',
        },
      ],
    });
 
    return { statusCode: 200, body: JSON.stringify(patientBundle) };
  }
 
  return { statusCode: 401, body: "No access token available" };
};

Additional resources

M2M Clients Lab