Can't find what you need? Tell us what's missing.
Take the survey
Ctrlk
Get a DemoCortex AcademyWebsiteStatusLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Plugin development reference

This article covers the core building blocks for developing Cortex plugins using the @cortexapps/plugin-core and @cortexapps/react-plugin-ui packages.

You'll learn how to read contextual information about the user and entity your plugin is running in, call Cortex APIs, reach external (non-Cortex) APIs without running into CORS issues, verify that incoming requests originated from Cortex using signed headers, and use Cortex's prebuilt UI components so your plugin matches the look and feel of the rest of the product.

Accessing contextual Cortex information from your plugin

The easiest way to access the plugin context is via the usePluginContext() hook.

import  from "@cortexapps/plugin-core/components";
import type React from "react";

const MyComponent = React.FC => () => {
  const context = usePluginContext();

  return (
    
      Plugin context
      
    
  );
};

export default MyComponent;

If you need to access the plugin context outside of a React component, you can use the CortexApi class directly. The CortexAPI class exposed from @cortexapps/plugin-core provides a method for accessing the context your plugin is running in, getContext().

Accessing Cortex APIs from your plugin

You can access Cortex APIs using @cortexapps/plugin-core’s CortexAPI. See the Cortex API docs for available API calls.

Accessing external APIs from your plugin

It's also possible to access non-Cortex APIs from your plugin. Because plugins are run in an iframe, typical fetch requests often get blocked by the browser's enforcement of CORS. However, when using the Cortex-provided template, the browser fetch is shimmed to call CortexApi.proxyFetch, a method for using Cortex as a proxy to make the request. For this reason, you should be able to use fetch() as you typically would in a web application.

If your browser fetch is not getting shimmed properly, make sure that your @cortexapps/plugin-core is up to date and you're using wrapping your app with <PluginProvider>. See the cookiecutter template for an example.

Request signing

The following headers are added to each request made by Cortex. Use these headers to verify that the request is valid and originated from Cortex:

  • x-cortex-timestamp

    • This header uses the current timestamp in millis, and is used to prevent replay attacks. Cortex signs the requests using the format <timestamp>.<body>.

  • x-cortex-timestamp-only-signature-256

    • This header calculates the SHA256 signature using only the timestamp. Use this header in environments where the HTTP request body is unavailable due to platform limitations.

  • x-cortex-signature-256

    • This header uses the SHA256 algorithm. For security best practices, it's recommended to use this header rather than x-cortex-signature.

  • x-cortex-signature

    • This header uses the SHA1 algorithm and exists for backward compatibility. SHA1 is considered unsafe and this signature should be considered deprecated.

Calculating the signature (an RFC2104 HMAC)

  1. Create a string with the value "$timestamp.$requestBody" if the request body is non-null OR "$timestamp" if the request body is null.

  2. Calculate an HMAC using the SHA256 algorithm. Use the secret you provided to Cortex as the key and the string from Step 1 as the payload.

  3. Verify that the x-cortex-signature-256 matches the HMAC calculated in Step 2.

Using Cortex UI components

Cortex UI components are available for import from @cortexapps/react-plugin-ui.

PreviousEditing a pluginNextMigrating Backstage plugins to Cortex

Last updated

Was this helpful?