Authentication and Token Management

Authenticate your application using API client credentials or a PBRS user account, then include the returned token in subsequent API requests.

Both authentication methods issue tokens with a 60-minute lifetime.

Before you begin

You need:

• A running PBRS REST API service.
• The configured API protocol, hostname, and port.
• Network access to that address.
• An enabled API client or a PBRS user account.

Use HTTPS when transmitting credentials and tokens across a network. Complete the certificate and listener configuration before making HTTPS requests.

Windows credentials used to install the API service are separate from the credentials used by your application.

Choose an authentication method

Use client credentials for an application configured as an API client in PBRS. Use user authentication when your integration authenticates with a PBRS user account.

Token requests do not require an existing access token.

Configure the base address

Use the protocol, hostname, and port configured for your installation:

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

The default local HTTP address is:

http://localhost:9000

Keep /api out of the base address. Append the complete endpoint path to it.

The client-credentials endpoint is /oauth2/token, not /api/oauth2/token. Do not add /v1 to either token endpoint.

The PowerShell examples below use $PbrsBaseUrl. Set it to your installation's address. Use localhost only when running the example on the PBRS server.

Authenticate with API client credentials

Create an API client

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

Request a token

Send a POST request to /oauth2/token.

The endpoint accepts application/x-www-form-urlencoded or application/json. The following example sends form-encoded fields and prompts for the secret instead of embedding it in the script.

$PbrsBaseUrl = "http://localhost:9000"
$PbrsClientId = Read-Host "PBRS client ID"
$PbrsSecretInput = Read-Host "PBRS client secret" -AsSecureString
$PbrsClientSecret = [System.Net.NetworkCredential]::new(
    "",
    $PbrsSecretInput
).Password

$PbrsTokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/oauth2/token" `
    -ContentType "application/x-www-form-urlencoded" `
    -Headers @{ Accept = "application/json" } `
    -Body @{
        grant_type    = "client_credentials"
        client_id     = $PbrsClientId
        client_secret = $PbrsClientSecret
    } `
    -ErrorAction Stop

if ([string]::IsNullOrWhiteSpace($PbrsTokenResponse.access_token)) {
    throw "PBRS did not return an access token."
}

$PbrsAccessToken = $PbrsTokenResponse.access_token

Use your HTTP library's form encoder so special characters in credentials are transmitted correctly.

Read the response

An illustrative successful response is:

{
  "access_token": "DemonstrationTokenValueNotACredential",
  "token_type": "bearer",
  "expires_in": 3600
}

The demonstration token is not a usable credential.

Authenticate with a PBRS user account

Send a POST request to /api/login/token.

The endpoint also accepts email instead of username. Supply one user identifier together with the password.

Both JSON and form-encoded requests are supported. This example uses JSON:

$PbrsBaseUrl = "http://localhost:9000"
$PbrsUserCredentials = Get-Credential -Message "Enter your PBRS user credentials"

$PbrsLoginBody = @{
    username = $PbrsUserCredentials.UserName
    password = $PbrsUserCredentials.GetNetworkCredential().Password
} | ConvertTo-Json

$PbrsTokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/login/token" `
    -ContentType "application/json" `
    -Headers @{ Accept = "application/json" } `
    -Body $PbrsLoginBody `
    -ErrorAction Stop

if ($PbrsTokenResponse.RequiresMfa -eq $true) {
    throw "PBRS returned an MFA challenge rather than an authenticated session."
}

if ([string]::IsNullOrWhiteSpace($PbrsTokenResponse.token)) {
    throw "PBRS did not return a usable user token."
}

$PbrsAccessToken = $PbrsTokenResponse.token

Read the response

Important response fields include:

The response may also include user profile and session information. Those values are not substitutes for the token.

Do not treat HTTP 200 alone as proof of successful user authentication. Check that the response is not an MFA challenge and contains a populated token.

Handle an MFA challenge

If RequiresMfa is true:

• Do not use the response as an authenticated session.
• Do not send MfaChallengeToken as an API access token.
• Do not automatically repeat the same login request.
• Contact your PBRS administrator to establish an authentication method supported by your integration.

MFA continuation is outside the public API workflow covered by this guide.

Authorize API requests

For either authentication method, send:

Authorization: bearer YOUR_ACCESS_TOKEN

Replace YOUR_ACCESS_TOKEN with:

• access_token from client-credentials authentication; or
• token from PBRS user authentication.

Use one space between bearer and the token. Do not surround the token with quotation marks or add another authorization prefix.

Treat tokens as opaque strings. Do not decode, modify, or assume a JWT structure.

Verify authenticated access

After running either authentication example, use the resulting $PbrsAccessToken to make a read-only request:

$PbrsSchedulerRunning = Invoke-RestMethod `
    -Method Get `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/Service/IsSchedulerRunning" `
    -Headers @{
        Accept        = "application/json"
        Authorization = "bearer $PbrsAccessToken"
    } `
    -ErrorAction Stop

$PbrsSchedulerRunning

This operation returns a JSON boolean indicating scheduler state. A response of false means the scheduler is not running; it does not mean authentication failed.

Access to the operation depends on the permissions available to your integration.

Ping does not require authentication. A successful Ping verifies connectivity, not token validity.

Manage token expiration

Reuse a valid token for subsequent requests instead of requesting a new token before every API call.

For client authentication, use expires_in to track the lifetime. For user authentication, use ExpiryDateEpoch to determine the expiration time.

Recommended application behavior:

1. Store the token and its expiration securely.
2. Request a replacement shortly before expiration, allowing a small safety margin for network delay and clock differences.
3. Replace the cached token after the new token request succeeds.
4. Coordinate renewal across concurrent requests to avoid unnecessary simultaneous token requests.
5. Stop using the previous token when it expires.

To obtain a replacement, repeat the original client-credentials or user-authentication request.

There is no documented public refresh-token flow. Do not assume that a refresh_token grant, logout operation, or token-revocation endpoint is available.

Do not assume that disabling an API client immediately invalidates tokens it has already issued.

Handle authentication failures

Incorrect credentials return HTTP 401 Unauthorized. The response may have no JSON body, so inspect the HTTP status before attempting to parse an error payload.

Authentication and authorization are separate. Obtaining a token does not guarantee permission to perform every operation.

Protected endpoints can return operation-specific errors. Do not treat every server error as an expired token or repeatedly request new tokens for unrelated failures.

Retry carefully

If an authenticated request is rejected because its token is no longer valid, obtain a replacement token and retry only when the operation is safe to repeat.

Do not automatically replay schedule creation, import, execution, or other state-changing requests after a timeout or ambiguous failure. Check whether the original request took effect before resubmitting it.

Bound retries and report persistent authentication failures rather than entering a continuous retry loop.

Protect credentials and tokens

• Use HTTPS for network transmission.
• Keep credentials in an application secret store.
• Keep token responses and authorization headers out of logs.
• Do not expose credentials or tokens in URLs, screenshots, support messages, or browser-delivered code.
• Limit access to the application configuration and runtime environment.
• Use the permissions required for your integration and verify access with your PBRS administrator.

The examples prompt for credentials for interactive testing. Production applications should retrieve credentials from their configured secret store.

Next step

Continue with Quick Start: Execute and Monitor a Schedule to submit an existing schedule, monitor its execution, and verify the result.