15.1.1.4. 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/names/caconnector

Return a list of defined CA connectors. Each item of the list is a dictionary with the CA connector information, including the name and defined templates, but excluding the CA connector data. This endpoint requires the enrollCERTIFICATE right.

GET /system/names/radius

Return the list of identifiers of all defined RADIUS servers. This endpoint requires the enrollRADIUS right.

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]

Return

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

or

JSON Parameters

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

Return

a json result with a boolean “result”: true

Example request 1:

POST /system/setConfig
key=splitAtSign
value=true

Host: example.com
Accept: application/json

Example request 2:

POST /system/setConfig
BINDDN=myName
BINDPW=mySecretPassword
BINDPW.type=password

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”.

Return

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

Parameters

  • key – The key to return.

Return

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

Rtype

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

Returns

a json result with the deleted value