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

Request JSON Object

key-value-pairs – a list of keyname=value pairs
<keyname>.type – type of the value: int or string/text or password. password will trigger to store the encrypted value
<keyname>.desc – additional information for this config entry

Response JSON Object

status (bool) – Status of the request
value – JSON object with a list of key-value pairs of the requested config entry changes with the value of update or insert

Request Headers

PI-Authorization – The authorization token

Example request:

POST /system/setConfig HTTP/1.1
Host: example.com
Content-Type: application/json

"splitAtSign": true
"totp.hashlib": "sha1"
"totp.hashlib.desc": "The hash algorithm used for TOTP tokens"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "splitAtSign": "update",
      "totp.hashlib": "update"
    }
  },
  "version": "privacyIDEA unknown"
}

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

GET /system/nodes¶

Return a list of nodes, that are known to the system.

Response JSON Object

nodes (list) – A list of JSON objects with the node name and uuid

Request Headers

PI-Authorization – The authorization token

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": [
        {
            "name": "node1",
            "uuid": "12345678-1234-1234-1234-1234567890ab"
        },
        {
            "name": "node2",
            "uuid": "12345678-4321-1234-1234-1234567890ac"
        }
    ]
  },
  "version": "privacyIDEA unknown"
}

New in version 3.10: Return node information with names and UUIDs

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 – (optional) The key to return

Response JSON Object

status (bool) – Status of the request
value – JSON object with a key-value pair of the config entries or
value – The value of the specified config entry

Request Headers

PI-Authorization – The authorization token

Example request 1:

GET /system/ HTTP/1.1
Host: example.com
Content-Type: application/json

Example response 1:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "AutoResync": "False",
      "splitAtSign": "True",
      "PrependPin": "True",
      "DefaultCountWindow": "10"
    }
  },
  "version": "privacyIDEA unknown"
}

Example request 2: Querying a specific system-configuration value

GET /system/totp.hashlib HTTP/1.1
Host: example.com
Content-Type: application/json

Example response 2:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": "sha1"
  },
  "version": "privacyIDEA unknown"
}

POST /system/test/(tokentype)¶: The call /system/test/email tests the configuration of the email token.

DELETE /system/(key)¶

delete a configuration key

Parameters

key (string) – configuration key name

Returns

a json result with the deleted value