Skip to main content
Version: 10.0

Authorization

The webPDF REST API web service endpoints are protected and require authorization for access. The authorization is in the form of an authorization token called an "access token".

Such a token authorizes the use of the API and can be issued in two ways:

  • the built-in authentication process using POST /authentication/user/login (see "Web service authentication"), which authenticates a user with credentials and issues an access token, or

  • via an external OAuth2 provider that issues an OAuth token (a JWT based "access token") that can be validated by the server during the API call.

The server (or API) can use both paths in parallel, or individual ones can be turned on or off.

Authorization configuration​

The integrated (local) authorization is available without additional configuration, while the use of OAuth2 tokens must first be configured in the server. Both ways of authorization can be configured via the Admin Portal.

Passing the authorization​

All API calls (web service endpoints) require an access token for authorization. The access token is passed to the endpoint in the Authorization header as Bearer: [access token].

Example: Calling the web service /converter with passing the access token (in blue) within the header of the request:

curl -X POST -i -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -d '{"converter": {"embedFonts": true,"jpegQuality": 90}}' http://localhost:8080/webPDF/rest/converter/605c045c129a40adb95d7623e279fe8a

The access token can be the token provided via the local authorization provider (via POST /authentication/user/login) or an OAuth2 JWT (JSON Web Token) provided by an external authorization provider.

Omitting this header or specifying an invalid token will result in a 401 Unauthorized error message when calling a web service endpoint.

Token format​

Access tokens understood by webPDF must be in "JSON Web Token" (JWT) format. This applies to tokens provided by local authorization as well as OAuth2 tokens originating from an external authorization provider.

The access tokens must be digitally signed, i.e. they must be available as "JSON Web Signature" (JWS) tokens. The signature must be based on RSA cryptography (consisting of a public and private key).