Issuing & Revoking Analytics Tokens

Learn how org admins can issue, manage, and revoke Power BI analytics tokens for tenant-level API access and auditing.

What's an analytics token?

An analytics token is a long, opaque string that Power BI uses to authenticate to the Foreman analytics API. Each token:

Is scoped to a single tenant — pinned at issue time and not affected by user tenant switching.
Is read-only — usable only against /api/analytics/v1/* endpoints. It cannot create or modify any records.
Expires automatically after the period you choose (30 / 90 / 180 / 365 days).
Can be revoked at any time. Revocation takes effect on the next API call.
Logs every call to an internal audit table you can review from the admin page.

Tokens always start with tmac_, which makes them easy to recognise in logs and gateway configurations.

Who can issue tokens?

Org admins of the tenant. The page is at Organization → Power BI Analytics.

Even though an admin issues the token, the token belongs to the tenant — it keeps working if that admin's account is removed or moved to another tenant.

Issuing a token

Open Power BI Analytics
Sign in as an org admin and navigate to Organization → Power BI Analytics.
Click "Issue token"
In the Analytics tokens panel, click the Issue token button.
Name the token
Use something descriptive like "Power BI — HQ executive dashboard" so you can identify it later.
Pick an expiry
30, 90 (default), 180, or 365 days. Shorter is safer; we recommend rotating at least once a year.
Copy the token immediately
It's shown exactly once. Store it in a password manager or secret store before closing the dialog.

Foreman never stores the plain-text token. We hash it on the way in and only ever check incoming requests against the hash. If you lose a token, you must issue a new one and update Power BI — we cannot recover it.

Recommended token strategy

One token per consumer. A separate token for each Power BI dataset (or each gateway) makes it easy to revoke a single dashboard without breaking everything else.
Document where each token lives. Use the token's name field to indicate the dashboard or gateway it's installed on.
Rotate annually. Even if nothing has gone wrong, rotating tokens limits the blast radius of an undetected leak.

Revoking a token

If a token has leaked, an employee who set it up has left, or a dashboard is being decommissioned:

Go to Organization → Power BI Analytics.
Find the token in the Analytics tokens table.
Click Revoke on its row.

Revoked tokens are kept in the table (greyed out and labelled "Revoked") so historical usage stays joinable in audit logs. Power BI refreshes using the revoked token will start failing on the next refresh with a 401 error.

Viewing usage

The Recent usage panel on the same page shows the last 20 API calls across all of your tenant's analytics tokens. Each row lists the token name, the endpoint hit, and the timestamp. Use this to:

Verify a newly-installed Power BI dataset is actually pulling data.
Spot tokens that haven't been used in months — candidates for revocation.
Investigate suspicious activity (calls from unexpected times, unusual endpoints).

Token expiry

When a token is within 7 days of expiring, the table row turns amber. When it expires, the row turns red and the token starts returning 401s. Power BI refreshes will fail silently once a token expires unless someone is monitoring the dataset's refresh history — make sure your BI team gets refresh-failure alerts in Power BI Service.