> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/guide/agents/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
The token can be any string without whitespace, long enough that it cannot be guessed. Backstage suggests generating one on the command line:
```bash theme={null}
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.
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:
```yaml theme={null}
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](https://backstage.io/docs/auth/service-to-service-auth) for the full option set.
Backstage reads external access tokens from configuration at startup, so restart it for the new entry to take effect.
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](#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
```text theme={null}
Summarize what is in our Backstage catalog: how many entities, which kinds, and who owns them
```
### Example prompts
```text theme={null}
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
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.
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 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.
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.
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
Cloud infrastructure and cost analysis
How CloudThinker gates tools that change state