Getting Started

Turn on the External API, trust a client, and make a first call. The first half of this page is a one-time setup for administrators; the second half is for anyone writing a script. The admin controls live on Settings > General, inside the collapsed Security card, in the External API access section.

Turn On the API

1. Go to Settings > General, expand the Security card, and find the External API access section.
2. Turn on Allow external API access.
3. Click Save Changes.

The same section also holds the MCP-only controls (Allow MCP connections, Tool calls per minute, MCP server URL). They are not part of the External API and are documented separately.

Add a Trusted Client

A trusted client is a client app that is allowed to call the API: Azure CLI, Azure PowerShell, or your own Entra app registration. Click Add client to open the Add Trusted Client wizard. It has three steps.

1. Choose the client

Under Scripts and apps, pick one of the three presets. The Display name (up to 100 characters) is used only inside StratoLens, in the Trusted clients list and the audit log. It is never written to Entra ID.

2. Configure the App Registration

Entra ID must let the client request the external_read scope on the StratoLens app registration. This is the StratoLens app registration (its Application (client) ID is the token audience, api://<clientId>), not the client you picked in step 1. The wizard pre-fills every value. Choose a tab:

Azure portal (default)

1. Open the StratoLens app registration's Expose an API blade using the link button.
2. Click + Add a scope, choose Admins only and Enabled, and fill in the scope name external_read, the display name Read StratoLens data (external API) and the description Allow scripts and approved client apps to read StratoLens data on behalf of the signed-in user. Click Add scope.
3. Click + Add a client application, paste the client ID from step 1, tick /external_read, then click Add application.

Steps that are already done are detected and hidden. If both are done, the tab says Already configured in Entra (detected).

Cloud Shell script

A PowerShell script to paste into Azure Cloud Shell as an App Registration owner. It keeps any other scopes and clients already on the app registration and is safe to re-run.

3. Verify

Click Verify and add. StratoLens re-reads the app registration and lists anything still missing under Not configured yet. Entra can take a minute to show changes, so wait and verify again if something you just added is still listed. The final screen shows ready-to-copy sign-in commands for the client you chose (the same snippets as in Sign In and Call the API).

To stop a client, click Remove on its row. The Remove Trusted Client dialog can also show how to remove the Entra pre-authorization. Copy those steps before confirming, because the dialog closes on removal. Removing a client from the list blocks it even if its Entra pre-authorization is still in place.

Restrict to Specific Users (Optional)

By default, once the API is on, every user with any StratoLens access may use it, with their normal roles and scope. To limit it to named users or groups:

1. In the External API access section, turn on Restrict API access to granted users and click Save Changes. This toggle is disabled while the master switch is off.
2. Go to Settings > Users and enable the External API access toggle on each user's or group's grant. It is in the Grant Access dialog (opened with Add Access) and in the Access Management modal (the row's info button).

Grants with the flag show a purple API badge in the Scope column. The toggle itself is shown only when both admin toggles are on and you can manage roles.

Sign In and Call the API

Sign in interactively as yourself, get a token for the StratoLens API (or let your tool do it), and call https://<host>/api/whoami to confirm everything works. In the snippets, <host> is your StratoLens address (for example stratolens.contoso.com) and <clientId> is the Application (client) ID of your StratoLens app registration. The wizard prints both pre-filled.

Azure CLI (any shell)

az rest gets, attaches and refreshes the token itself.

az login
az rest --url "https://<host>/api/whoami" --resource "api://<clientId>"

Token only (curl, Postman, any HTTP tool)

Bash shown. In Windows PowerShell type curl.exe, because curl there is an alias for Invoke-WebRequest.

TOKEN=$(az account get-access-token --scope "api://<clientId>/external_read" --query accessToken -o tsv)
curl -H "Authorization: Bearer $TOKEN" "https://<host>/api/whoami"

PowerShell 7+

Connect-AzAccount
$token = (Get-AzAccessToken -ResourceUrl "api://<clientId>").Token
Invoke-RestMethod -Uri "https://<host>/api/whoami" -Authentication Bearer -Token $token

Windows PowerShell 5.1

Connect-AzAccount
$token = [System.Net.NetworkCredential]::new('', (Get-AzAccessToken -ResourceUrl "api://<clientId>").Token).Password
Invoke-RestMethod -Uri "https://<host>/api/whoami" -Headers @{ Authorization = "Bearer $token" }

Custom app (MSAL or any delegated OAuth flow)

Request exactly the scope api://<clientId>/external_read. Do not request access_as_user, and do not request both. Then send the token as a bearer header.

GET https://<host>/api/whoami
Authorization: Bearer <access token>

Worked Examples

Once whoami works, every other route is the same call with a different path. With az rest, pass extra query parameters in the URL and quote the whole URL.

# Changes in a time window, for one subscription
az rest --resource "api://<clientId>" --url "https://<host>/api/getResourceGraphChanges?start=2026-10-01T00:00:00Z&end=2026-10-06T00:00:00Z&subscriptionId=<subId>"

# Cost by hierarchy for a month
az rest --resource "api://<clientId>" --url "https://<host>/api/cost-explorer-summary?startDate=2026-09-01&endDate=2026-09-30"

# Orphaned resources
az rest --resource "api://<clientId>" --url "https://<host>/api/orphaned-resource-recommendations"

The route pages explain each parameter: getResourceGraphChanges, cost-explorer-summary and orphaned-resource-recommendations.

How the Controls Behave

Two layers must both agree before a call works. Entra ID must have the client pre-authorized for external_read; otherwise Entra refuses to issue the token, typically with a consent error such as AADSTS65001. external_read is an admin-consent scope, so no user can consent to an arbitrary app for it, even in tenants that allow user consent. StratoLens must have the client on the Trusted clients list.

Defaults and timing

All toggles

Off. While the master switch is off, every external token is rejected on every route.

Toggle and list changes

Apply immediately on the server that saved them and within about 60 seconds everywhere else.

Per-user grant changes

Apply on the user's next request.

Token lifetime

About an hour. When calls start returning 401, get a new token. az rest refreshes automatically.

Deployment script re-runs

Re-running the StratoLens deployment's app registration script keeps every trusted client's pre-authorization.

Audit log

Settings saved, trusted client added or removed, and a user's external API access changed are all recorded under Access & Security. Individual API calls are not logged.

If something fails, the troubleshooting table on the Authentication page maps every error message to its fix.