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/documentation¶: returns an restructured text document, that describes the complete configuration.

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/(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/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"
}

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

DELETE /system/(key)¶

delete a configuration key

Parameters:

key (string) – configuration key name

Returns:

a json result with the deleted value

POST /system/hsm¶: Set the password for the security module

GET /system/hsm¶: Get the status of the security module.

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/test/(tokentype)¶: The call /system/test/email tests the configuration of the email token.

GET /system/names/radius¶: Return the list of identifiers of all defined RADIUS servers. This endpoint requires the enrollRADIUS right.

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/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"
}

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

DELETE /system/user-cache¶

Delete all entries from the user cache.

Response JSON Object:

status (bool) – Status of the request

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,
    "deleted": 42
  },
  "version": "privacyIDEA unknown"
}