> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/streamline/plugins/creating-plugins/plugin-development-reference.md). # 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. ```ts 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()`. ```ts import from "@cortexapps/plugin-core"; import types from "@cortexapps/plugin-core"; // fetch information about the currently-signed-in Cortex user const getCurrentCortexUser = async (): Promise => ; // if the plugin is running inside of a catalog entity details page, fetch information about that entity const getCurrentCortexEntity = async (): Promise => ; ``` ## Accessing Cortex APIs from your plugin You can access Cortex APIs using `@cortexapps/plugin-core`’s `CortexAPI`. See the [Cortex API docs](https://docs.cortex.io/api/) for available API calls. ```ts import from "@cortexapps/plugin-core"; // fetch deploys for the current entity if the plugin is running on a domain, resource, or service details page const fetchDeploysForCurrentEntity = async () => { const context = await CortexApi.getContext(); if (!context?.entity) const = context.entity; const response = await CortexApi.proxyFetch(`https://api.getcortexapp.com/api/v1/catalog/$/deploys`); return response.json(); }; ``` ## 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 ``. See the [cookiecutter template](https://github.com/cortexapps/cookiecutter-cortex-plugin/blob/master/%7B%7Bcookiecutter.project_name%7D%7D/src/components/App.tsx) 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 `.`. * `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](https://datatracker.ietf.org/doc/html/rfc2104.html) 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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/streamline/plugins/creating-plugins/plugin-development-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.