Skip to main content
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​

ScopeDescription
pd_AdminWebApiAccess to the Admin API for administrative operations
pd_ConnectWebApiAccess 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.

Example​

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