Authentication and Token Management

Authenticate with an ATRS user account or an API client, then send the returned token with protected requests.

Before you begin

Record the API base address, without /api or /v1.
Use trusted HTTPS when sending credentials across a network.
Obtain an ATRS user account or create an API client in Options → REST API → API Clients.
Confirm the account or client has access to the actions your application needs.

Choose an authentication method

Method	Request	Token field	Expiration field
API client	`POST /api/OAuth2/token`	`access_token`	`expires_in`, in seconds
ATRS user	`POST /api/Login/token`	`token`	`ExpiryDateEpoch`, Unix epoch seconds

An API client is suitable for a backend integration with its own configured credentials. Use the user flow when the integration authenticates an ATRS user. Both token requests are sent without a bearer token.

Authenticate an API client

Enter the generated client ID and secret. This example sends a JSON request and saves the returned token:

$AtrsBaseUrl = "https://atrs.example.com:9001"
$AtrsClientId = Read-Host "ATRS client ID"
$AtrsSecret = Read-Host "ATRS client secret" -AsSecureString
$AtrsClientCredential = New-Object System.Management.Automation.PSCredential($AtrsClientId, $AtrsSecret)
$AtrsClientBody = @{
    grant_type = "client_credentials"
    client_id = $AtrsClientId
    client_secret = $AtrsClientCredential.GetNetworkCredential().Password
} | ConvertTo-Json
$AtrsClientToken = Invoke-RestMethod -Method Post `
    -Uri "$AtrsBaseUrl/api/OAuth2/token" -ContentType "application/json" `
    -Headers @{Accept="application/json"} -Body $AtrsClientBody -TimeoutSec 30
if ([string]::IsNullOrWhiteSpace($AtrsClientToken.access_token)) {
    throw "No client access_token returned"
}
$AtrsAccessToken = $AtrsClientToken.access_token

An illustrative response looks like this; use your returned token and lifetime:

{"access_token":"EXAMPLE_TOKEN","token_type":"bearer","expires_in":86399}

The response includes these fields:

Field	What to do with it
`access_token`	Send as the bearer token on protected requests.
`token_type`	Identifies the token scheme.
`expires_in`	Use the returned lifetime to calculate when to request another token.

Treat the token as an opaque credential. Use the returned expiration information rather than hard-coding a duration.

Authenticate an ATRS user

Use this alternative flow with the user’s ATRS sign-in identifier and password. It also sets $AtrsAccessToken:

$AtrsBaseUrl = "https://atrs.example.com:9001"
$AtrsCredentials = Get-Credential -Message "ATRS user credentials"
$AtrsLoginBody = @{
    username = $AtrsCredentials.UserName
    password = $AtrsCredentials.GetNetworkCredential().Password
} | ConvertTo-Json
$AtrsLogin = Invoke-RestMethod -Method Post `
    -Uri "$AtrsBaseUrl/api/Login/token" `
    -ContentType "application/json" `
    -Headers @{ Accept = "application/json" } -Body $AtrsLoginBody
if ([string]::IsNullOrWhiteSpace($AtrsLogin.token)) {
    throw "No user token returned. Inspect the authentication response."
}
$AtrsAccessToken = $AtrsLogin.token

The login model includes username, password and email. The example uses username; use the identifier configured for the ATRS account. Read token and ExpiryDateEpoch from the response. A missing token means authentication is incomplete.

For example, the relevant fields in a user response have this form:

{"token":"EXAMPLE_TOKEN","ExpiryDateEpoch":1792180800}

The timestamp is illustrative. Track the value returned by your installation.

Send the token and verify access

Run the following after either flow, in the same PowerShell session. It calls the protected GET /api/Service/IsSchedulerRunning operation:

$AtrsHeaders = @{Authorization="Bearer $AtrsAccessToken"; Accept="application/json"}
$AtrsRunning = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/Service/IsSchedulerRunning" -Headers $AtrsHeaders -TimeoutSec 30
if ($AtrsRunning -isnot [bool]) { throw "Expected a JSON boolean" }
Write-Host "Authenticated protected read succeeded. Scheduler running: $AtrsRunning"

Expect a JSON boolean. true means the scheduler is running; false means it is stopped. Either value is a successful protected read. Ping is unauthenticated, so it cannot verify your token.

Reuse $AtrsBaseUrl and $AtrsHeaders in the other PowerShell guides. If you start a new session, run authentication and this header setup again.

Manage expiration

Cache tokens on your backend. For an API client, calculate expiration from expires_in; for a user, use ExpiryDateEpoch. Request a replacement shortly before expiration by repeating the original flow, allowing a small margin for clocks and network delays. Coordinate replacement across concurrent requests.

After renewal, rebuild the bearer header with the replacement token. Resume monitoring an existing execution with the same ExecutionId rather than submitting it again.

Keep passwords, client secrets and tokens out of browser code, shared collections, source control and diagnostics.

Troubleshooting

Symptom	Next action
Token request returns 401	Check the selected installation, credential type and credentials. The response can be empty.
No token is extracted	Use `access_token` for API clients or `token` for users.
Protected call returns 401	Check expiry and send exactly one `Bearer` prefix. Obtain a replacement token if needed.
Token works but an action is denied	Check the caller’s permissions for that operation and resource.
JSON parsing fails on an error	Keep the HTTP error; inspect content type and body before parsing.

Continue with Quick Start: Execute and Monitor a Schedule.