System endpoints

This is the REST API for system calls to create and read system configuration.

The code of this module is tested in tests/test_api_system.py

GET /system/documentation

returns an restructured text document, that describes the complete configuration.

POST /system/setDefault

define default settings for tokens. These default settings are used when new tokens are generated. The default settings will not affect already enrolled tokens.

JSON Parameters:
  • DefaultMaxFailCount – Default value for the maximum allowed authentication failures
  • DefaultSyncWindow – Default value for the synchronization window
  • DefaultCountWindow – Default value for the counter window
  • DefaultOtpLen – Default value for the OTP value length – usually 6 or 8
  • DefaultResetFailCount – Default value, if the FailCounter should be reset on successful authentication [True|False]

a json result with a boolean “result”: true

POST /system/setConfig

set a configuration key or a set of configuration entries

parameter are generic keyname=value pairs.

remark In case of key-value pairs the type information could be
provided by an additional parameter with same keyname with the postfix “.type”. Value could then be ‘password’ to trigger the storing of the value in an encrypted form
JSON Parameters:
  • key – configuration entry name
  • value – configuration value
  • type – type of the value: int or string/text or password. password will trigger to store the encrypted value
  • description – additional information for this config entry


JSON Parameters:
  • pairs (key-value) – pair of &keyname=value pairs

a json result with a boolean “result”: true

Example request 1:

POST /system/setConfig

Host: example.com
Accept: application/json

Example request 2:

POST /system/setConfig

Host: example.com
Accept: application/json
GET /system/gpgkeys

Returns the GPG keys in the config directory specified by PI_GNUPG_HOME.

Return:A json list of the public GPG keys
GET /system/random

This endpoint can be used to retrieve random keys from privacyIDEA. In certain cases the client might need random data to initialize tokens on the client side. E.g. the command line client when initializing the yubikey or the WebUI when creating Client API keys for the yubikey.

In this case, privacyIDEA can create the random data/keys.

Query Parameters:
  • len – The length of a symmetric key (byte)
  • encode – The type of encoding. Can be “hex” or “b64”.

key material

POST /system/hsm

Set the password for the security module

GET /system/hsm

Get the status of the security module.

GET /system/(key)
GET /system/

This endpoint either returns all config entries or only the value of the one config key.

This endpoint can be called by the administrator but also by the normal user, so that the normal user gets necessary information about the system config

  • key – The key to return.

A json response or a single value, when queried with a key.


json or scalar

POST /system/test/(tokentype)

The call /system/test/email tests the configuration of the email token.

DELETE /system/(key)

delete a configuration key

JSON Parameters:
  • key – configuration key name

a json result with the deleted value