Backstage

The Flagsmith Backstage Plugin brings feature flag management directly into your Backstage developer portal. It provides three components:

• Feature Flags Tab — A full flag list with environment states, tags, and toggle status.
• Overview Card — A quick summary of your feature flags for entity overview pages.
• Usage Card — A chart showing flag usage metrics over time.

Prerequisites

• A running Backstage instance.
• A Flagsmith account with an Admin API Key.
• Your Flagsmith Project ID.

Installation

Install the plugin from your Backstage app root:

yarn --cwd packages/app add @flagsmith/backstage-plugin

Configuration

Add the Flagsmith proxy configuration to your app-config.yaml:

proxy:
  endpoints:
    '/flagsmith':
      target: 'https://api.flagsmith.com/api/v1'
      headers:
        Authorization: Api-Key ${FLAGSMITH_API_TOKEN}

tip

If you are self-hosting Flagsmith, replace the target URL with your own Flagsmith API address, e.g. https://flagsmith.example.com/api/v1.

Adding Components to Entity Pages

Edit your packages/app/src/components/catalog/EntityPage.tsx to add the Flagsmith components.

Feature Flags Tab

Import and add the FlagsTab as a new tab on your entity page:

import { FlagsTab } from '@flagsmith/backstage-plugin';

// Inside your entity page layout, add a new tab:
<EntityLayout.Route path="/feature-flags" title="Feature Flags">
  <FlagsTab />
</EntityLayout.Route>

Overview Card

Add the FlagsmithOverviewCard to your entity overview page:

import { FlagsmithOverviewCard } from '@flagsmith/backstage-plugin';

// Inside your overview grid:
<Grid item md={6}>
  <FlagsmithOverviewCard />
</Grid>

Usage Card

Add the FlagsmithUsageCard to display flag usage metrics:

import { FlagsmithUsageCard } from '@flagsmith/backstage-plugin';

// Inside your overview grid:
<Grid item md={6}>
  <FlagsmithUsageCard />
</Grid>

Entity Annotations

Annotate your entities in catalog-info.yaml so the plugin knows which Flagsmith project to display:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    flagsmith.com/project-id: '<YOUR_PROJECT_ID>'
spec:
  type: service
  owner: my-team
  lifecycle: production

Annotation	Required	Description
flagsmith.com/project-id	Yes	The numeric ID of your Flagsmith project.

tip

The organisation ID is automatically derived from the project data, so you don't need to specify it separately.

Getting Your Credentials

Admin API Key

1. Log in to Flagsmith.
2. Navigate to Organisation Settings → API Keys.
3. Click Create API Key and ensure Is admin is enabled.
4. Copy your Admin API Key.

Project ID

1. Open your Flagsmith project.
2. Go to Project Settings → General.
3. Enable JSON references in your Account Settings if not already enabled.
4. Click the JSON data dropdown and select Project.
5. The Project ID is shown as the id field in the JSON (e.g., "id": 1).