Authenticated Zambdas

We will cover what authenticated Zambdas are, when you should use them and how to create one. If you have not already read the Writing Zambdas guide, we recommend you do so before continuing.

Overview of Authenticated Zambdas

If you want to control who can invoke your Zambda, you should use authenticated Zambdas.

Authenticated Zambdas require that the requester present a valid authentication token with their request. Additionally, the Actor making the request must have the necessary permissions to invoke the specific authenticated Zambda that they are calling.

Example use cases:

Receiving lab data from another API.
Running custom code before updating a FHIR resource, for example if you want to permit users to change their address and validate that the address is valid.
Checking if a user has partially completed onboarding and returning their progress.

Creating and Executing an Authenticated Zambda

If you do not already have a Zambda, you can create one by following the Writing Zambdas guide.

You can use the Oystehr SDK or the curl command to test your Zambda. You will need to replace the following values:

your_zambda_id with the ID of the Zambda
your_access_token placeholder with your access token from the Oystehr Console (opens in a new tab) getting started section.
your_oystehr_project_id with the ID of the project that the Zambda belongs to. You can find this in the Project Settings (opens in a new tab)

Execute a Zambda with the v3 SDK:

import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});
 
const result = await oystehr.zambda.execute(
  {
    id: 'your_zambda_id',
    name: 'Oystehr User',
    // you can submit additional data to your Zambda here
  }
);

If you try modifying your access token or project ID and you will see that the request fails with an Unauthorized error. Now only actors in your project with sufficient permissions can invoke your Zambda.

Granting Permission to Invoke Authenticated Zambdas

In order to invoke an authenticated Zambda, the actor making the request must be granted the Zambda:InvokeFunction action over the specific Zambda that they are calling. Here are some example access policies that grant permission to invoke authenticated Zambdas:

Grant permission to invoke a specific authenticated Zambda Function

{
  "rule": [
    {
      "action": ["Zambda:InvokeFunction"],
      "resource": ["Zambda:Function:2419a78e-4c0a-411d-b8e2-90dc081f5efa"],
      "effect": "Allow"
    }
  ]
}

Grant permission to invoke all authenticated Zambda Functions

{
  "rule": [
    {
      "action": ["Zambda:InvokeFunction"],
      "resource": ["Zambda:Function:*"],
      "effect": "Allow"
    }
  ]
}

Writing Zambdas Public