Install and Configure the PBRS API

Install the PBRS REST API service on your PBRS server, configure its connection settings, create an API client, and verify connectivity.

Before you begin

You need:

• A working PBRS installation.
• Administrator access to the PBRS server.
• Windows credentials for the API service installation.
• Network access between your application and the PBRS server.
• A secure location for storing API credentials.

The REST API service is installed from within PBRS. Windows credentials used during installation are separate from the API credentials your application uses to authenticate requests.

1. Install the PBRS API service

1. Open PBRS on the server.
2. Open Options.
3. Select REST API to open PBRS API Configuration.
4. Select the API Settings tab.
5. Under API Status, click Install API.
6. In the authentication dialog, enter your Windows Username, Password, and Domain, if applicable.
7. Click OK.

PBRS installs the API as a Windows service.

When prompted to open firewall port 9000:

1. Click Yes to allow access through that port, if appropriate for your network.
2. Click OK on the confirmation message.

If your organization manages firewall rules separately, have your administrator configure the required access.

If the API service is already installed, proceed to the connection settings.

2. Configure the protocol and port

On the API Settings tab, locate Configuration Settings.

Set the following fields:

The default configuration is HTTP on port 9000.

Ensure that your firewall permits connections to the port you configure. If you select a different port, the installation's port-9000 firewall rule does not cover that port.

Protocol and Port cannot be changed while the API service is running. To change them on an existing installation:

1. Coordinate the interruption with applications using the API.
2. Click Stop under API Status.
3. Change the protocol or port.
4. Update the corresponding firewall and certificate configuration as needed.
5. Click Start.
6. Update calling applications to use the new address.

Configure HTTPS

Before using HTTPS, configure:

• A valid server certificate matching the hostname applications will use.
• The certificate and its private key in the intended Local Machine certificate store on the PBRS server.
• A Windows HTTPS certificate binding on the selected port, using that certificate's thumbprint and the matching certificate-store name.
• Certificate-chain trust on the calling machines.
• Firewall access to the selected port, scoped to the intended clients.

Keep the server certificate and CA trust configuration separate. Installing a server certificate does not automatically make clients trust its issuing certificate authority. Do not place the server's leaf certificate in Trusted Root Certification Authorities as a general installation step; configure trust in the appropriate issuing CA chain.

Inspect existing Windows HTTPS bindings before adding or replacing a binding. Confirm the selected port, certificate thumbprint, and certificate store, and preserve the details needed to restore a working configuration.

Complete the certificate installation and binding steps in Configure HTTPS for the PBRS API, then select https and the corresponding port in Configuration Settings.

Port 9001 is an example HTTPS port, not a required or default HTTPS port. The PBRS port, Windows binding, firewall rule, and application URL must agree.

Selecting https alone does not install a certificate or create the Windows certificate binding. The direct Windows binding configuration does not require an IIS website.

After starting the API, complete the HTTPS connection and authentication tests below.

3. Start the API service

1. On the API Settings tab, locate API Status.
2. Click Start.
3. Verify that the status reads The PBRS API Service is running.

The button changes to Stop while the service is running.

To stop the API service, return to this screen and click Stop. Applications cannot make successful API requests while the service is stopped.

The API service and the PBRS scheduler perform different functions. Starting the API service makes API requests available; it does not by itself verify scheduler status or report delivery.

4. Create an API client

Create a client for an application that will use client-credentials authentication:

1. Select the API Clients tab.
2. Click Add.
3. Enter a descriptive Client Name.
4. Leave Enabled checked.
5. Store the generated Client Id and Client Secret securely.
6. Click Save & Close.

PBRS generates the client ID and secret automatically.

Your application uses these credentials with /oauth2/token to obtain an access token. Store the credentials in your server-side application or secret store. Do not expose them in browser-delivered JavaScript or public repositories.

Alternative: PBRS user authentication

Applications can also authenticate with a PBRS username and password through /api/login/token.

Use the credentials and request format associated with your chosen authentication method:

See Authentication and Token Management for complete request examples.

5. Set the connection address

Build your API base address from the configured protocol, server hostname, and port:

{scheme}://{host}:{port}

For a local connection using the defaults:

http://localhost:9000

localhost refers to the machine making the request. Use it only when your application or test command runs on the PBRS server.

For applications running elsewhere, use the PBRS server's reachable hostname or IP address. When using HTTPS, use a hostname that matches the server certificate.

Append the endpoint path

Keep /api out of the base address, then append the complete endpoint path.

Most endpoint paths begin with /api. The client-credentials token endpoint does not.

The API version label is v1; do not add /v1 to endpoint paths.

6. Test the connection

Run this command on the PBRS server to test the default HTTP configuration:

curl --request GET --url "http://localhost:9000/api/service/ping" --header "Accept: application/json"

In Windows PowerShell, use curl.exe:

curl.exe --request GET --url "http://localhost:9000/api/service/ping" --header "Accept: application/json"

A successful Ping returns:

1

Ping does not require authentication.

If you configured a different protocol or port, update the URL before running the command.

Test HTTPS

For an HTTPS installation, test the actual HTTPS address using the hostname covered by the certificate.

For example, in Windows PowerShell:

curl.exe --request GET --url "https://pbrs.example.com:9001/api/service/ping" --header "Accept: application/json"

Replace pbrs.example.com and 9001 with your certificate hostname and configured port.

Run the test from a machine that will use the API. Keep certificate verification enabled; do not use --insecure or -k to make the test pass.

Confirm that the request completes without a certificate error and returns 1. A successful HTTP test does not verify HTTPS, and inspecting a certificate binding alone does not verify that clients can connect.

Test remote access

Repeat the test from the machine that will run your integration. Replace localhost with the PBRS server's reachable hostname or IP address.

If the local test succeeds but the remote test fails, check:

• Server-name resolution.
• Network routing.
• Firewall access to the configured port.
• Listener configuration.
• Certificate trust and hostname matching for HTTPS.

7. Verify authentication

After Ping succeeds:

1. Obtain a token using API client credentials or PBRS user credentials.
2. Include the token in the Authorization header with the bearer prefix.
3. Call a protected read-only operation that your integration is authorized to use.
4. Verify that the response contains the expected information.

For HTTPS deployments, obtain the token and make the protected request through the same HTTPS hostname and port tested above.

Access tokens expire after 60 minutes. Incorrect credentials return HTTP 401 Unauthorized.

A successful Ping confirms that the service is reachable. A successful protected request additionally verifies authentication and access to that operation.

Maintain the HTTPS configuration

Record the certificate's expiration date and plan renewal before it expires.

When replacing the certificate, verify the new certificate's hostname, private key, certificate store, and chain. Update the Windows binding to use the replacement certificate where required, and confirm the API's configured protocol and port.

Coordinate any required service interruption and retain the previous binding details for recovery. Repeat both the remote HTTPS Ping and a protected API request after renewal or binding changes.

8. Prepare reporting accounts and destinations

Before creating or executing schedules, confirm that:

• Required Power BI, SSRS, or Power BI Report Server accounts are configured in PBRS.
• Those accounts can access the intended reports.
• Required delivery credentials and filesystem permissions are configured.
• Target folders and other required resources are available.
• Your application has the identifiers required by each API operation.

Use public discovery operations where available. Obtain administrator-supplied account identifiers where account listing is not available through the public API.

For your first execution test, use an existing schedule with a known report and a controlled delivery destination. Confirm that the schedule runs successfully from PBRS before executing it through the API.

Troubleshooting

Next steps

Continue with Authentication and Token Management to authenticate your application.

Then follow Quick Start: Execute and Monitor a Schedule to submit a schedule, track its execution, and verify delivery.