Connect Aphex to Power BI

Things to know before you get started:

• You will need the Desktop Power BI application downloaded onto your device.

• You must be a Project Admin to set up the integration.

In addition to our built in reporting app, Aphex Insight we also provide an integration with Power BI so that teams can customise their reports and hunt for insight.

In this guide we will go through the key steps to start analysing your data in Power BI. Where necessary we will include links to more advanced features throughout.

Enable Integration

---

The Power BI Integration is enabled at a project level so that every team has control over who can access their data. To start, head to your project in Aphex Planner and locate the Integrations page.

To enable the data source:

• Open your project

• Click your project title in the top left and select Integrations from the menu

• Locate the Power BI section and toggle Enable Source

Generate a Token

---

Once you've enabled the Power BI source, you’ll be able to copy your project's unique URL endpoint.

To keep your data secure, the endpoint won’t return any data unless the request includes a valid token. The token is shown once only, so be sure to copy it before closing the window. If it expires or you forget to save it, you can generate a new one at any time.

To generate a token:

• On the Integrations page, click + Generate New Token

• Give your token a name so that people know what it's being used for

• Click Generate Token

• Select Copy Token

• Click Done to close the window

How Tokens Work

Authentication Power BI connects using two parts: a project-specific URL and a bearer token. The token acts like a secure key - it proves that the request is allowed to access the data behind the URL.

Expiry Tokens expire automatically after 90 days, or can be manually revoked at any time from the project’s Integration settings.

Multiple tokens supported You can create as many tokens as you need - useful if you’re connecting different tools or templates.

Naming tokens Each token must be given a name when created. This helps you track where it’s being used (e.g. “PPC Dashboard” or “Client Reporting Suite”).

Usage tracking You’ll be able to see the timestamp of last use and the token creator for each token so you know what’s active and what can be cleaned up.

Download a Template

---

Next up: pick a template. We’ve created a set of ready-to-use Power BI dashboards so you don’t have to build your own from scratch. Choose one that fits your reporting needs, then you’ll be ready to connect your project data.

To download a template:

• Visit Aphex's Resource Hub

• Pick a Template

• Enter in your details & email

• Open the email and click the download link

• A PBIT file will download to your device

Download a Template or build your own using the API Reference Doc

Load Data into Power BI

---

Next step: open your template Before the template can show anything, it needs to connect to your project. This is where you plug in the values you saved earlier and let Power BI load your project data into the report.

To connect the template to your Aphex Project:

• Open the PBIT file in Power BI Desktop

• You’ll be prompted to enter three values:

  • Project API URL

  • Token

  • Project Name (this is just for display inside the report)

• Click Load

• Power BI will securely request your project data and load it into the report

With your data loaded, the dashboard is ready to use. If you’re familiar with Power BI, you can tweak visuals, add filters, or expand the reports to fit your project’s workflow.

Common Errors

• If you receive a warning about installing the latest version of Power BI Desktop you can most likely continue on without issue (although updating your software is usually a good idea!)

• Ensure your token is valid, and that you've copied the Project API URL correctly

Access Web Content Prompt When Power BI prompts you with the Access Web Content window, it’s asking how to authenticate your connection to the API.

Since authentication is handled through the bearer token you already entered, no additional credentials are required here:

• Select “Anonymous” as the authentication method, then click Connect.

This tells Power BI not to apply any other login method. Using other options like “Windows” or “Organizational Account” may block the request or cause errors.

Got a great report template? Why not give back to the Aphex Community and share it with us [email protected]

Common Connection Issues

---

Most connection issues come down to one of a few predictable causes. This section walks through the ones we see most often and how to fix them.

Access Web Content: Use Anonymous Authentication

When Power BI prompts you with the Access Web Content window, make sure Anonymous is selected. This is important because the API uses your token for authentication - selecting any other method (like Windows or Organizational Account) will block the connection.

To use Anonymous Authentication:

• In the Access Web Content window, select Anonymous

• Make sure no other method is selected, and that no other information has been entered into the window (like Web API Key, or Organizational Account)

• You may also need to ensure the Privacy Level is set to None or Public to avoid errors when refreshing

To prompt the Access Web Content window:

• Open the template

• Click Transform Data

• Select Data Source Settings

• Click Edit Permissions at the bottom of the window

• Make sure that Credentials match:

  • Type: Anonymous

  • Privacy Level: None

• If needed, select Edit to open the Access Web Content window

Example Errors

“The 'Authorization' header is only supported when connecting anonymously.” These headers can be used with all authentication types: Accept, Accept-Charset, Accept-Encoding, etc.

• This means Power BI tried to connect using an authentication method that doesn’t support your bearer token (such as Windows or Organizational Account).

“We couldn’t authenticate with the credentials provided.”

• This suggests Power BI could be using the wrong method (e.g. "Organizational Account") instead of Anonymous.

“The remote server returned an error: (401) Unauthorized.”

• This means the API blocked the request - often because Power BI tried to use Windows or Organizational credentials instead of the token.

Response Size Limit (32mb)

By default, your request will return data from the 5 most recent Published Versions. If your project’s dataset is too large, the connection may fail to load. Unless you're on an Enterprise plan, the API response must be under 32MB. You can reduce the amount of data being returned by using query parameters to limit the response size.

Read more about query parameters in our API Reference Doc

Example Error Messages

“The response payload size exceeds the limit.”

• A clear sign the API returned more than Power BI is allowed to process.

“DataFormat.Error: We reached the end of the buffer.”

• This usually means the dataset was too large for Power BI to handle in one response.

“Unable to connect to the data source. The connection was closed before the data could be retrieved.”

• This can sometimes be triggered when the response is too large and times out during transfer.

Ways to reduce data size

You can use the following parameters individually or in combination:

• Limit the number of versions Append ?limit=3 or ?limit=2 to your API URL → Example: https://app.aphex.co/au/power-bi...?limit=3

• Exclude resource data Append ?resource=false to your API URL → Useful if you don’t need labour or plant or material reporting.

• Exclude delay status data Append ?status=false to your API URL → Useful if you do not need to report on delay reasons.

• Exclude blocker data Append ?blockers=false to your API URL → Useful if you do not need to report on blockers.

You can combine parameters like: ?limit=3&resource=false&status=false

Replace Expired Credentials

Bearer tokens used for the Power BI integration are valid for 90 days. After that, the connection will stop working until you generate a new token.

If your token has expired, simply return to the project’s Integrations page, revoke the old token, and generate a new one. You’ll need to re-enter the new token into your report to restore the connection.

To replace an expired Token:

• Generate a new Token from inside your Aphex Project

• Open your template in Power BI

• Click Transform Data then Edit Parameters

• Select Edit Token

• Delete your old token and add your new one, then select Save

• You may need to Reload Data

Example Errors

“The remote server returned an error: (401) Unauthorized.”

• This usually means the token is missing, expired, or no longer valid.

Set up Automatic Refresh

---

Once your report is connected, you can configure scheduled refresh in Power BI to keep your data up to date automatically.

We suggest setting the refresh to run a few hours (or the day after) your team typically creates the weekly Published Version in Aphex. That way, your dashboard will always reflect the latest plan, without any manual updates.

To set up Scheduled Refresh inside Power BI:

• Publish your report to Power BI Service

  • In Power BI Desktop, go to File → Publish → My Workspace (or your team’s shared workspace).

• Open dataset settings

  • In Power BI Service, go to your workspace → Datasets tab.

  • Find the dataset linked to your Aphex report and click the More Options (⋯) → Settings

• Set authentication method to Anonymous

  • Under Data source credentials, confirm that the method is set to Anonymous.

  • Also check that Privacy Level is set to None or Public, if prompted.

• Enable “Skip test connection”

  • To avoid false errors during refresh setup, make sure to enable “Skip test connection”.

  • This setting tells Power BI not to validate the connection in advance, which is fine, because the bearer token is already embedded in the query.

• Set up scheduled refresh

  • Expand the Scheduled refresh section and turn it on:

  • Choose daily or weekly refresh

• Save your changes

  • Your dashboard will now stay in sync with the latest Published Plan - no manual exports or updates needed.

  Visit the Microsoft Documentation to learn more about Scheduled Refresh in Power BI