C.2. Web Services

SavaPage uses XML-RPC, JSON-RPC and RESTful API for its public Web Services. Both protocols are Open Standard, lightweight and have support for all major programming and scripting languages.


The range of Web Services will grow upon request. Please tell us if you need extra methods.

C.2.1. XML-RPC

The secure endpoint is: https://savapage:8632/xmlrpc/v1

C.2.1.1. onetime-auth.createToken

With this method a Trusted Third Party (TTP) acquires a one-time token for Web App user authentication.

The requesting User Name and returned Token must be offered to the Web App by hidden HTTP POST input names auth_user and auth_token. The Web App decrypts the token and honours the authentication request if the offered and encrypted Users match and the token is not expired.





The TTP API key as set in the web-login.ttp.apikey configuration property.



The User Name to authenticate. See Section 3.1, “Login”.

User Alias mapping is applied.




The one-time authentication token holding the encrypted User Name and token creation time.

The expiration criterion in milliseconds is set in the web-login.ttp.token.expiry-msecs configuration property.

Table C.1. XML-RPC method: onetime-auth.createToken


This method is used by moodle-block_savapage.


TTP Web App Login authentication must be enabled by setting the web-login.ttp.enable configuration property to Y.


The secure endpoint is: https://savapage:8632/jsonrpc/v1

The following configuration properties apply:

Configuration propertyDescription


The secret key to be passed as X-Auth-Key HTTP header.


A CIDR Set of allowed client IPv4 and/or IPv6 addresses. When void access is denied for all clients.

Table C.2. JSON-RPC Configuration Properties

See Section 4.11.14, “Config Editor” on how to set these items.

The sections below discuss the individual methods. All methods default to the same response layout in case of an error.

JSON-RPC : Basic Error

Figure C.1. JSON-RPC : Basic Error

C.2.2.1. systemStatus

This method returns the system status as enum value. READY indicates the system is ready to use and users have access to the Web App. All other values indicate that user access is denied, because: system SETUP is needed, MAINTENANCE is in progress, or the system is temporarily UNAVAILABLE due to running batch jobs (database backup, user synchronization, database cleanup).


Although the system can have multiple "deny status" at the same time, the single most important status is returned, in the order SETUP, MAINTENANCE, UNAVAILABLE.

JSON-RPC : systemStatus (request)

Figure C.2. JSON-RPC : systemStatus (request)

JSON-RPC : systemStatus (response)

Figure C.3. JSON-RPC : systemStatus (response)

# sample request
curl --request POST --header "X-Auth-Key: 7961b5ec-bee4-11e7-8731-406186940c49" \
     --data '{"jsonrpc":"2.0","id":"reference","method":"systemStatus"}' \
# sample response
  "jsonrpc" : "2.0",
  "id" : "reference",
  "result" : {
    "data" : {
      "@type" : "enum",
      "value" : "READY"

C.2.2.2. authUserSource

This method authenticates an external user against the configured User Source.

JSON-RPC : authUserSource (request)

Figure C.4. JSON-RPC : authUserSource (request)

JSON-RPC : authUserSource (response)

Figure C.5. JSON-RPC : authUserSource (response)

# sample request
curl --request POST --header "X-Auth-Key: 7961b5ec-bee4-11e7-8731-406186940c49" \
     --data '{"jsonrpc":"2.0","id":"reference","method":"authUserSource", \

# sample response
  "jsonrpc" : "2.0",
  "id" : "reference",
  "result" : {
    "data" : {
      "@type" : "boolean",
      "value" : true
# sample error
  "jsonrpc" : "2.0",
  "id" : "reference",
  "result" : false,
  "error" : {
    "code" : -32603,
    "message" : "ldapserver:636 [No route to host (Host unreachable)]",
    "data" : {
      "@type" : "BASIC",
      "reason" : "ldapserver:636"

C.2.3. RESTful API


RESTful Web Services is a Feature Preview that is partly operational and impermanent. The preview is offered to provoke feedback based on real world use. Please tell us your requirements.

The secure endpoint is: https://savapage:8632/restful/v1

Services are described with curl examples.

C.2.3.1. RESTful Public Services

C. GET /system/version

curl -k -X GET "https://savapage:8632/restful/v1/system/version"

# sample response
SavaPage 1.2.0-rc (Build 20200121)

C. GET /tests/http/request

curl -k -X GET \

# sample response
  "remoteAddr" : "[2021:661:4cc6:1:5561:96ff:ca11:d4a]",
  "remoteHost" : "[2021:661:4cc6:1:5561:96ff:ca11:d4a]",
  "remotePort" : 53840,
  "localAddr" : "",
  "serverName" : "savapage.example.com",
  "serverPort" : 443,
  "headers" : {
    "Accept" : "*/*",
    "User-Agent" : "curl/7.47.0",
    "X-Forwarded-Proto" : "https",
    "X-Forwarded-Host" : "savapage.example.com",
    "Connection" : "keep-alive",
    "X-Forwarded-For" : "2021:661:4cc6:1:5561:96ff:ca11:d4a",
    "Host" : "savapage.example.com",
    "X-Forwarded-Server" : "savapage.example.com"

C.2.3.2. RESTful Admin Services

Access to Admin Services is controlled by Basic HTTP Authentication.

Configuration propertyDescription


Basic Authentication Username.


Basic Authentication Password.


A CIDR Set of allowed client IPv4 and/or IPv6 addresses. When void access is allowed for all clients.

Table C.3. RESTful Admin Services Configuration Properties

C. POST /tests/echo

curl -k -u admin:password -X POST \
     "https://savapage:8632/restful/v1/tests/echo" \
     -H "Content-Type:text/plain" -d "Hello World!"

# response
Hello World!

C. GET /documents

# GET JSON info of first 5 documents sorted by creation datetime descending
curl -k -u admin:password -X GET \

# ... sorted ascending
curl -k -u admin:password -X GET \

# GET JSON info of first page chunk of 2 proxy printed documents
# type = all (default) | in | out | pdf | print | ticket

curl -k -u admin:password -X GET \

# sample response
[ {
  "id" : 6263,
  "ext_id" : "",
  "type" : "print",
  "title" : "Document A",
  "created" : "2019-09-13T09:18:38+0200",
  "store" : false
}, {
  "id" : 6258,
  "ext_id" : "c5a9dd70e931",
  "type" : "print",
  "title" : "Document B",
  "created" : "2019-09-12T09:49:48+0200",
  "store" : false
} ]

C. GET /documents/<id>

# GET JSON info of document id 6272
curl -k -u admin:password -X GET \

# sample response
  "id" : 6272,
  "ext_id" : "d2a3a71c11e9",
  "type" : "print",
  "title" : "Invoice 20190248",
  "created" : "2019-09-16T12:29:15+0200",
  "store" : true

C. GET /documents/ext_id=<ext_id>

# GET JSON info of document with ext_id d2a3a71c11e9
curl -k -u admin:password -X GET \

C. GET /documents/<id>/pdf

# GET stored PDF document 6272
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents/6272/pdf" > 6272.pdf

C. GET /documents/ext_id=<ext_id>/pdf

# GET stored PDF document with ext_id d2a3a71c11e9
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents/ext_id=d2a3a71c11e9/pdf" \
     > d2a3a71c11e9.pdf

C.2.3.3. RESTful User Services

Access to User Services is controlled by User ID and UUID.

C. POST /documents/print

# Print file "lorem-ipsum.txt" to SavaPage as user "janet" with UUID credentials
curl -v -k -u janet:97008e2c-d8b2-11e9-aa13-406186940c49 \
     -H "Content-Type: multipart/form-data" -H "Accept: application/json" \
     -F "file=@lorem-ipsum.txt" -X POST \ 


RESTful Print is used by the SavaPage Android Print App.


A RESTful Print maps to the reserved Queue /webservice. To exclusively accept prints from specific IP addresses see Section 4.7.2, “Edit Queue”.