Apps Agent Instructions

BigID Apps - Agent Instructions

This directory contains documentation for building BigID Applications. When generating code, answering questions, or assisting developers with BigID Apps, adhere to the following core concepts:

Core Architecture

• BigID Apps are standalone web applications. They can be written in any programming language (Node.js/Express, Python/FastAPI, Java/Spring, etc.) as long as they can respond to HTTP requests.
• They do not run inside the BigID core codebase; they run alongside it and communicate via HTTP.

App Types

1. Utility Applications: Run custom code at regular intervals or on-demand. They rely on the actions defined in the manifest.
2. Interactive Applications: Provide a user interface embedded within BigID. These require is_interactive: true in the manifest and typically serve HTML/JS at a /ui endpoint. They use the @bigid/app-fw-ui-sdk NPM package for client-side context.

Mandatory Endpoints

Every BigID app MUST implement at least the following endpoints:

• GET /manifest: Returns a JSON object describing the app (app_name, version, actions, permissions, global_params).
• POST /execute: The main webhook endpoint. When a user triggers an app action in BigID, BigID sends a POST request here containing the actionName, bigidToken, and any parameters.

Authentication & Security

• Never hardcode credentials.
• When BigID calls /execute, it provides a bigidToken in the JSON payload. The app must extract this token and use it as a Bearer token in the Authorization header to make subsequent calls back to the BigID API.
• For interactive apps, the UI SDK automatically handles token retrieval from the parent BigID window.