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.

Additional resources

M2M Clients Messaging