Backstage

Connect Backstage to CloudThinker for software catalog inventory, service ownership and dependency context, and metadata gap review

Connect your Backstage instance to let Alex (Cloud Engineer) read the Software Catalog: which services exist, who owns them, what they depend on, and which entries are missing the metadata your teams rely on.

Backstage authenticates with a static external access token you add to your Backstage configuration. Reading the catalog is the whole connection; the one change an agent can make is to a catalog location you name, and it asks you before every one.

Prerequisites

• A Backstage instance reachable from CloudThinker over HTTPS.
• Access to the Backstage configuration file where you can add a static external access token.
• Optional, for updating a registered location: Backstage 1.50 or later, the first release with the catalog’s location-update endpoint. Reading, registering, and removing locations work on earlier releases.

Setup

1. Generate a token

   The token can be any string without whitespace, long enough that it cannot be guessed. Backstage suggests generating one on the command line:

   node -p 'require("crypto").randomBytes(24).toString("base64")'
   

   Store the result in a secret manager or an environment variable, and dedicate it to CloudThinker so you can revoke it without disturbing anything else.

2. Add it as a static external access token

   Add an entry of type static under backend.auth.externalAccess in your Backstage app configuration. The subject identifies the caller in Backstage’s own logs:

   backend:
     auth:
       externalAccess:
         - type: static
           options:
             token: ${CLOUDTHINKER_TOKEN}
             subject: cloudthinker
           accessRestrictions:
             - plugin: catalog
   

   The accessRestrictions block is what keeps the token narrow: plugin: catalog rejects requests to any other Backstage plugin. Leave it out and, in Backstage’s words, “the access method has unlimited access to all functionality of all plugins”. See Backstage’s service-to-service authentication guide for the full option set.

3. Restart Backstage

   Backstage reads external access tokens from configuration at startup, so restart it for the new entry to take effect.

4. Add the connection in CloudThinker

   Navigate to Connections → Backstage and enter:

   • Backstage URL: the Backstage backend root, such as https://backstage.example.com
   • Service token: the token you generated

   Click Connect. CloudThinker reads a single catalog entity to verify the token, and the status turns Connected.

Enter the Backstage root only, over https. Do not append /api/catalog, any other path, a query string, a fragment, or credentials — CloudThinker adds the catalog path itself and rejects a URL that carries anything else.

Connection details

Field	Description	Example
Backstage URL	The HTTPS Backstage backend root, with no path, query, fragment, or credentials	https://backstage.example.com
Service token	The static external access token you added to your Backstage configuration	—

Required permissions

Restrict the token to the catalog plugin and nothing else:

Restriction	Effect
plugin: catalog	The token reaches the Software Catalog and is rejected everywhere else. This is the restriction to set
No restrictions	The token reaches every plugin in your Backstage instance. Avoid this

That single line covers everything an agent reads. Registering, updating, or removing a catalog location additionally needs the token to be allowed to create, update, and delete locations — see Write access. If you only want agents to read, give the token no location write access at all.

Backstage’s permission and permissionAttribute restrictions apply only where the permissions framework is enabled, which is off by default — on a default instance neither setting restricts anything. Do not rely on them as your read-only guarantee; the plugin restriction is always enforced.

Agent capabilities

Once connected, agents can read what your catalog knows about your services.

Capability	Description
Catalog inventory	List entities with their kind, namespace, owner, type, and lifecycle
Catalog shape	Summarize the catalog by kind, type, and owner
Service context	For one named entity: owner, lifecycle, system, domain, source repository, documentation, APIs, and relations
Metadata gaps	Count the returned entities missing an owner, lifecycle, source-repository link, or documentation link
Location lookup	Read one registered catalog location by its ID

Answers are bounded: a lookup returns up to 15 entities across 3 pages by default, and never more than 50 entities across 5 pages, so agents say “returned 15” rather than “15 exist”. A metadata gap is a gap in the catalog, not in the service — an entity with no owner recorded means nobody filled that field in, and agents report it that way.

Verify the connection

Summarize what is in our Backstage catalog: how many entities, which kinds, and who owns them

Example prompts

Which components in Backstage have no owner set
The owner, system, and dependencies of the payments-api component in Backstage
Which Backstage entries are missing a documentation link and which to fix first

Write access

Agents cannot create, edit, or delete catalog entities — entities come from the locations your catalog ingests. The only change this connection can make is to a location: register a new one, point an existing one somewhere else, or remove one.

Every one of those asks you first. The agent states the action, the location ID or target URL, and the URL prefix it treats as yours, then waits. Two rules bound what an approval can do:

• The target must be an https URL under the prefix you approved; a target outside it is refused before any request is made.
• Updating or removing a location first checks its current target is under the same prefix, so an approval for one prefix cannot reach a location that belongs to another team.

Removing a location removes the entities it produced from your catalog. Read the target in the prompt before you approve, and approve only a location you recognize as yours.

Troubleshooting

Failed to connect to Backstage

CloudThinker reports one message for every connection failure, so check the likely causes in order: the URL points somewhere other than the Backstage backend root, or redirects (CloudThinker never follows a redirect); the token is not in backend.auth.externalAccess, was mistyped, or Backstage has not been restarted since you added it; the token’s accessRestrictions do not include plugin: catalog; or Backstage is unreachable from CloudThinker.

Invalid Backstage URL or connection configuration

The address is not a plain HTTPS host root, or the service token is empty or carries a line break. Remove any path, query, fragment, or embedded credentials from the URL, and re-copy the token as a single line with no surrounding quotes.

The agent reports fewer entities than Backstage shows

The answer came from a bounded page of results, or the token cannot see the rest. Narrow the question to the component, system, or domain you care about rather than asking for everything.

An agent says it cannot edit a catalog entity

That is correct, and no permission changes it. Entities are produced by the locations your catalog ingests, so edit them at their source. An agent can register, repoint, or remove a location for you, with your approval.

Updating a location fails

The location-update endpoint arrived in Backstage 1.50. On an earlier release, remove the location and register the new target instead.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Restrict the token to the catalog — one plugin: catalog line is the difference between a catalog reader and a token that reaches every plugin you run.
• Rotate by replacing the entry — a static token does not expire on its own; replace it in your Backstage configuration and update the connection on your own schedule.

Related

Alex Agent

Cloud infrastructure and cost analysis

Approval

How CloudThinker gates tools that change state