Version: 4.1 (2026 H2)

Authentication

The primedocs Web API uses OAuth 2.0 with Bearer tokens for authentication. Clients must be registered in primedocs.config before they can obtain access tokens.

Overview

Authentication is handled via the Identity Server (IdS) included in the primedocs installation. After a client is registered, it can request an access token using the client_credentials grant type.

The access token must then be included in the Authorization header of all API calls:

Authorization: Bearer <access_token>

Client Registration

To register a client, add an entry to primedocs.config. See primedocs.config for details.

Token Request

Access tokens are requested from the token endpoint:

POST https://{instance}/ids/connect/token

The request body must include:

client_id: the registered client ID
client_secret: the client secret
grant_type: must be client_credentials
scope: the required scope (e.g., pd_AdminWebApi or pd_ConnectWebApi)

API Scopes

Scope	Description
`pd_AdminWebApi`	Access to the Admin API for administrative operations
`pd_ConnectWebApi`	Access to the Connect API and Connect Session API for document generation

End-to-end example

1. Request an access token (client_credentials grant at the token endpoint):

POST https://{instance}/ids/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=CustomApiClient&client_secret=CustomClient_Secret_123&grant_type=client_credentials&scope=pd_ConnectWebApi

2. Example response from the token endpoint:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pd_ConnectWebApi"
}

3. Use the access token: include the access_token in the Authorization header of every API call:

GET https://{instance}/webapi/api/v3/{datasourceId}/Admin/Users?page=1&pageSize=10
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

note

If a token expires (401 Unauthorized), simply request a new one via step 1. The token lifetime depends on the Identity Server configuration.

Authentication errors

The following responses apply to endpoints of the Admin API, Connect API and Connect Session API protected through the Identity Server. Requests without a valid access token return HTTP 401 Unauthorized. SCIM endpoints validate their tokens separately and use SCIM error responses. Distinguish the following responses when handling errors:

Situation	Response
No Bearer token is supplied	HTTP `401` with a Bearer challenge in the `WWW-Authenticate` header. Do not assume a JSON response body.
The supplied token fails validation	HTTP `401` with a JSON body containing `error: "invalid_token"` and `error_description`. The description depends on the validation failure and is not a stable error code.

Handle the HTTP status first. If a token has expired, request a new token and retry with it. For other token errors, check the token and authentication configuration. Do not retry indefinitely with the same invalid token, and do not require invalid_token in both the response header and body: these are different response paths.

Example

See the individual API pages for full PowerShell examples showing how to obtain and use access tokens:

Overview​

Client Registration​

Token Request​

API Scopes​

End-to-end example​

Authentication errors​

Example​