Skip to content
English
Log a Support Call Customer portal
  • There are no suggestions because the search field is empty.

Manage the PBRS API Service and API Clients

Learn how to install, configure, start, and stop the PBRS API service and create API clients in the PBRS application.

The PBRS REST API runs as a Windows service on the PBRS server. Use the REST API settings in PBRS to install and control the service, configure its connection settings, and manage the API clients used by integrations.

For request formats, authentication examples, endpoint documentation, and integration workflows, use the PBRS Developer Hub.

Before you begin

Ensure that you have:

  • A working PBRS installation.
  • Administrator access to the PBRS server.
  • The Windows credentials requested by the API installer.
  • An available network port for the API.
  • Permission to configure the required firewall rules.
  • A secure location for storing API credentials.

The Windows credentials requested during installation are separate from the API credentials that applications use to authenticate requests.

Open the PBRS API configuration

  1. Open PBRS on the server.
  2. Select Options.
  3. Select REST API to open PBRS API Configuration.
  4. Select the API Settings tab.

Install the API service

If the API service has not been installed:

  1. Locate API Status.
  2. Select Install API.
  3. Enter the requested Windows Username, Password, and Domain, if applicable.
  4. Select OK.
  5. Confirm the installation when prompted.
  6. If PBRS asks to open firewall port 9000, approve the change only if it is appropriate for your network.
  7. Select OK when PBRS confirms that the installation is complete.

PBRS installs the API as a Windows service.

If your organization manages firewall rules separately, have the appropriate administrator configure access to the API port.

Configure the protocol and port

On the API Settings tab, locate Configuration Settings.

Configure the following fields:

Field Description
Protocol Select http or https.
Port Enter the port on which the API will listen.

The default configuration is HTTP on port 9000.

The default local base URL is:

http://localhost:9000

The base URL consists of the protocol, server hostname, and port:

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

Do not include /api or /v1 in the base URL.

localhost refers to the computer making the request. Use it only when the request is sent from the PBRS server. Applications running on another computer must use the reachable hostname or IP address of the PBRS server.

For example:

http://pbrs-server:9000

If you change the configured port, ensure that the firewall permits connections to the new port. A firewall rule created for port 9000 does not automatically cover another port.

Change an existing configuration

The API service must be stopped before you change the Protocol or Port settings:

  1. Under API Status, select Stop.
  2. Change the Protocol or Port.
  3. Update the corresponding firewall and certificate configuration.
  4. Select Start.
  5. Update calling applications to use the new base URL.

Configure HTTPS

Selecting https in PBRS does not install or bind a certificate automatically.

An HTTPS configuration requires:

  • A server certificate that matches the hostname applications will use.
  • The certificate’s private key on the PBRS server.
  • A Windows HTTP certificate binding on the selected port.
  • A trusted certificate chain on the calling computers.
  • Firewall access to the selected HTTPS port.

Complete the certificate and Windows binding procedure before starting the API with HTTPS.

See Configure HTTPS for the PBRS API for the complete procedure.

Start the API service

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

The button changes to Stop while the API service is running.

To stop the service, return to API Status and select Stop. Applications cannot send successful API requests while the API service is stopped.

The API service and the PBRS scheduler are separate. Starting or stopping the API service does not start or stop the scheduler.

Create an API client

Applications using client-credentials authentication require an API client.

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

PBRS generates the Client Id and Client Secret automatically.

Where practical, create a separate API client for each application and environment. This makes credentials easier to manage without affecting unrelated integrations.

Treat the Client Secret as a password. Do not include it in documentation, screenshots, support requests, shared files, source control, or browser-delivered JavaScript.

Applications use the generated credentials with the /oauth2/token endpoint to obtain an access token.

See Authentication and Token Management for the authentication request and token-handling instructions.

Replace or revoke an API client

To replace an application’s credentials:

  1. Create a new API client and store its generated credentials securely.
  2. Update the application to use the new Client Id and Client Secret.
  3. Confirm that the application can obtain an access token and call the API.
  4. Disable or remove the old client from the API Clients tab.

To revoke an application’s access without replacing its credentials, disable or remove its API client and save the change. Do not reuse a Client Secret that may have been exposed.

Verify the API service

Send the following request from the PBRS server:

GET http://localhost:9000/api/Service/Ping

If you configured a different protocol or port, update the URL accordingly.

A successful request returns HTTP 200 OK with:

1

The Ping endpoint does not require authentication.

A successful Ping confirms that the API service is reachable and responding. It does not verify scheduler status, reporting-account access, rendering, or report delivery.

Verify remote access

Repeat the Ping request from the computer that will run the integration. Replace localhost with the PBRS server’s reachable hostname or IP address.

When using HTTPS, use a hostname that matches the server certificate.

If Ping works on the PBRS server but not from another computer, check:

  • The server hostname or IP address.
  • Name resolution.
  • Network routing.
  • Firewall access to the configured port.
  • The configured protocol and port.
  • Certificate validity, trust, and hostname matching when using HTTPS.

Troubleshooting

Protocol and Port cannot be changed

Stop the API service before changing the Protocol or Port settings.

The API service does not start

Confirm that:

  • The configured port is not already being used.
  • The selected protocol and port match the intended configuration.
  • The required HTTPS certificate binding exists when using HTTPS.

The connection is refused

Confirm that:

  • The API service is running.
  • The request uses the correct protocol, hostname, and port.
  • The request is being sent to the PBRS server.
  • The configured port is accessible.

The connection times out

Check network routing and firewall access to the configured API port.

An HTTPS certificate error occurs

Check:

  • The certificate’s validity period.
  • The hostname used in the request.
  • The certificate’s subject or subject alternative names.
  • Certificate-chain trust on the calling computer.
  • The Windows certificate binding for the configured port.

Related documentation