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

Roles for the Admin API

For the Admin API the scope alone is not enough: every area additionally requires a role. A client receives its roles via the roles attribute of its registration in primedocs.config, for example roles="SysAdmin" or roles="TemplateAdmin, SnippetAdmin". Without the attribute, the default roles without SysAdmin and Developer apply. Which role each area requires is listed under Admin API: Roles of the API client. If the role is missing, the API responds with HTTP 403.

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 and a problem document with code 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.
The supplied token fails validation	HTTP 401 with the header WWW-Authenticate: Bearer error="invalid_token". The response does not state the reason for the rejection. It is in the server log under the correlationId.
The Identity Server cannot be reached to check the token	HTTP 503 with code AuthenticationUnavailable. The token is not invalid. Retry the call later with the same token.

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.

Example

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

• Admin API
• Connect API
• Connect Session API