Backstage plugin

What the card shows

Up to eleven cards, each read live for the entity the catalog entry is annotated with. A card appears only where it applies and when your key carries it. The cards are theme-aware, so they stay legible in both Backstage themes.

All five means an organization, a business unit, a team, a business area or a repository.

Each card carries its provenance: MEASURED when the number came out of your environment, and DECLARED when somebody configured it (the technology landscape, or a headcount declared for a business area). People cost is the one figure built on a value your company set, its average salary, and the card says so.

For a business area or a repository, Compliance reads the entity's own repositories. The controls that are kept per team come from the teams that own those repositories: the card names them, says how many repositories no team owns, and says they are not applicable when no team owns any. They are never counted as met.

The card reads the public read-only Platform API through the Backstage backend proxy, so your org-scoped key is injected server-side and never reaches the browser.

Before you start

This guide targets @scalequality/backstage-plugin 0.2.2, the version currently published on npm.

Install and configure

Five steps: add the package, create the key, configure the proxy, add the card, and tell Backstage which ScaleQuality entity each catalog entry maps to.

# from your Backstage app root
yarn --cwd packages/app add @scalequality/backstage-plugin@^0.2.2

proxy:
  endpoints:
    '/scalequality':
      target: https://app.scalequality.io/v1
      changeOrigin: true
      headers:
        Authorization: 'Bearer ${SCALEQUALITY_API_KEY}'

import { EntityScaleQualityCard } from '@scalequality/backstage-plugin';

// inside the entity page grid, e.g. the overview content:
<Grid item md={6}>
  <EntityScaleQualityCard />
</Grid>

metadata:
  annotations:
    scalequality.io/repo-id: <project-uuid>   # a repository, or one module of a monorepo
    # or: scalequality.io/team-id: <team-uuid>
    # or: scalequality.io/area-id: <business-area-uuid>
    # or: scalequality.io/bu-id: <bu-uuid>
    # or: scalequality.io/org-id: <org-uuid>

curl https://app.scalequality.io/v1/catalog \
  -H "Authorization: Bearer sq_live_..."

API reference

Everything the plugin reads is public, read-only and gated by the API key. The same endpoints back any other internal developer portal, Port included.

scope is one of org, bu, team, area or repo, and id is the uuid from the catalog. A key only reads inside its own organization: an id from another tenant answers 403 or 404, an id that does not exist answers 404, and any other scope value answers 400. A widget asked for a kind of entity it is not read for also answers 400. A key that does not carry the scope a widget needs answers 403 on that widget's endpoint, and on the entity endpoint that signal is simply left out.

Response shape

Every endpoint answers with the same envelope: the subject, when it was measured, and one entry per signal carrying the value, its unit, a status, its provenance and a deep link back into ScaleQuality.

{
  "subject":    { "type": "team", "id": "...", "name": "Payments" },
  "measuredAt": "2026-10-10T09:12:44.108Z",
  "signals": {
    "health":      { "value": 74, "unit": "score", "status": "warn",
                     "provenance": "MEASURED", "data": { ... }, "deepLinkUrl": "..." },
    "security":    { "value": 12, "unit": "count", "status": "warn",
                     "provenance": "MEASURED", "data": { ... }, "deepLinkUrl": "..." },
    "compliance":  { "value": 9,  "unit": "count", "status": "warn",
                     "provenance": "MEASURED", "data": { ... }, "deepLinkUrl": "..." },
    "engMaturity": { "value": 3,  "unit": "level", "status": "warn",
                     "provenance": "MEASURED", "data": { ... }, "deepLinkUrl": "..." },
    "techRadar":   { "value": 42, "unit": "count", "status": "ok",
                     "provenance": "DECLARED", "data": { ... }, "deepLinkUrl": "..." },
    "licenses": { ... }, "coverage": { ... }, "evolution": { ... }, "ai": { ... },
    "peopleCost": { ... }, "initiatives": { ... },
    "durability": { ... }, "codeMaturity": { ... }
  }
}

status is one of ok, warn, risk or unknown. provenance is part of the contract, not decoration: MEASURED means the number came out of your environment, and DECLARED means somebody configured it. A null value means it has not been measured yet, and the card renders its empty state for it.

Troubleshooting

Almost every failed install lands on one of these.